OpenAPI

OpenAPI 仕様 (OAS) は、REST API の記述形式です。 Swagger(英語) は、REST API を作成、文書化、使用するための、この仕様に基づくツールのセットです。詳細については、「Swagger のドキュメント(英語) 」を参照してください。

PyCharm は、YAML および JSON ファイル内の OpenAPI 定義に対するコーディング支援と、OpenAPI 仕様に基づくサーバースタブ、クライアントライブラリ（SDK）、ドキュメントの生成のための Swagger Codegen との統合を提供します。

エンドポイントツールウィンドウを使用して、OpenAPI 仕様で定義されているすべてのエンドポイントを表示できます。

OpenAPI 仕様を作成する

PyCharm は専用の OpenAPI Specification ファイルタイプと、関連するコーディング支援を認識します。これらは、OpenAPI 仕様バージョンの定義を持つ通常の YAML または JSON ファイルです。

OpenAPI 仕様を手動で作成する

Project ツールウィンドウで Alt+Insert を押し、コンテキストメニューから OpenAPI Specification を選択します。
ファイルの名前を指定し、仕様バージョンとファイル形式を選択します。

エディターで開いた OpenAPI 仕様では、ガターアイコンを使用して仕様セクションをすばやく追加します。

IDE 設定の Languages & Frameworks | OpenAPI Specifications で Gutter icons for quick specification edits チェックボックスを使用して、ガターアイコンを無効にすることができます。

形式とバージョンに応じて、新しい OpenAPI 仕様ファイルには次のテンプレートが含まれています：

                    openapi: 3.0.0
                    info:
                        title: Title
                        description: Title
                        version: 1.0.0
                    servers:
                        - url: 'https'
                    paths:

                
    

                    {
                        "openapi": "3.0.0",
                        "info": {
                            "title": "Title",
                            "description": "Title",
                            "version": "1.0.0"
                        },
                        "servers": [
                            {
                                "url": "https"
                            }
                        ],
                        "paths": {

                        }
                    }

                
    

                    swagger: "2.0"
                    info:
                        title: Title
                        description: Title
                        version: 1.0.0
                    host: www
                    schemes:
                        - https
                    paths:

                
    

                    {
                        "swagger": "2.0",
                        "info": {
                            "title": "Title",
                            "description": "Title",
                            "version": "1.0.0"
                        },
                        "host": "www",
                        "schemes": [
                            "https"
                        ],
                        "paths": {

                        }
                    }

                
    

空の YAML または JSON ファイルから始める場合は、 opnp または swag と入力し、 Tab を押して対応するライブテンプレートを挿入できます。

別のファイルから定義を参照する

OpenAPI 3.0 では、 $ref(英語) キーワードを使用して、任意の場所でホストされている定義を参照できます。 PyCharm は、パスの補完、検証、迅速なナビゲーションを提供します。補完では、PyCharm が現在のファイルや外部ファイルのコンテキストを理解し、関連する要素へのポインターの使用を提案します。

$ref キーワードを入力します。
外部定義へのパスの入力を開始します。

Ctrl+B を押すと、参照するファイルと要素にすばやく移動できます。

OpenAPI 仕様をプレビューする

統合された Swagger UI または Redoc UI を使用して、OpenAPI 仕様をプレビューできます。 OpenAPI 仕様ファイルがエディターで開かれている場合、右上隅のおよびを使用してプレビューを表示または非表示にします。

Swagger UI と Redoc UI を切り替えるには、プレビュー領域にカーソルを置き、をクリックします。

エディターを分割して水平方向にプレビュー

デフォルトでは、エディターとプレビューは垂直（並列）に分割されており、ワイドモニターに便利です。また、水平方向に分割してプレビューをエディターの下部に表示することもでき、縦長ディスプレイの方が便利です。

エディターの右上隅にあるをクリックして、エディタープレビューペインを開きます。
をクリックして、エディターとプレビューを水平に分割します。

リモート OpenAPI 仕様を追加する

プロジェクトの OpenAPI 仕様で定義したエンドポイント URL は、コード補完で使用できます。外部仕様のクライアントコードを記述している場合は、エンドポイント URL を自動補完するためにプロジェクトにファイルとして追加する必要はありません。関連するリモート仕様へのリンクを追加できます。

設定ダイアログ（Ctrl+Alt+S ）で、 Languages & Frameworks | OpenAPI Specifications を選択します。
Remote Specifications リストでをクリックして、OpenAPI 仕様ファイルの URL を指定するか、 SwaggerHub(英語) で OpenAPI 仕様を見つけます。

を使用して、変更された仕様を再ロードします。

プライベート OpenAPI 仕様(英語)を追加するには、API キーを指定します。

自己ホスト型 SwaggerHub オンプレミス(英語)インスタンスから OpenAPI 仕様を追加するには、インスタンスの URL を指定します。

OpenAPI 仕様の比較

新しい仕様バージョンがある場合は、古いバージョンと比較して、互換性があることを確認する必要があります。 1 つの方法は、差分 Ctrl+D を見て、変更された行を比較することです。ただし、すべての変更が互換性にとって重要であるとは限りません。 PyCharm は、OpenAPI 仕様の構造を比較し、変更されたパス、パラメーター、レスポンス、互換性を損なう可能性のあるその他の要素の概要を作成できます。

Project ツールウィンドウで、2 つの OpenAPI 仕様ファイルを選択し、右クリックして Compare OpenAPI Specifications を選択します。

これにより、変更された仕様要素の要約を含む Markdown ファイルが生成されます。エディター内でファイルが開き、変更を簡単に移動できるプレビューパネルが表示されます。最初に選択したファイルと比較して、2 番目に選択したファイルの変更が表示されます。

OpenAPI 仕様からコードを生成する

有効な OpenAPI 仕様を開いている場合、PyCharm はそこからコード生成を提案します：

ガターでをクリックし、『openapi file』を実行を選択します。 PyCharm は、指定した場所にソースコードファイルを生成し、ファイルを開くか、別モジュールとしてプロジェクトにインポートできるオプション付きの通知を表示します。

Swagger Codegen 実行構成

PyCharm は、特定のファイルで初めてコード生成を実行するときに、 OpenAPI/Swagger Code Generator 実行構成を作成します。実行構成を変更するには、実行 | 実行構成の編集を開いて必要な構成を選択するか、ガターでをクリックして実行構成を変更を選択します。

OpenAPI/Swagger Code Generator 実行構成の上部で、次の共通オプションを構成できます。

一般的なパラメーター

項目	説明
名前	実行構成の名前を指定して、編集または実行時に他の構成の間ですばやく識別できるようにします。
プロジェクトファイルとして保存	実行構成設定を含むファイルを保存して、他のチームメンバーと共有します。デフォルトの場所は .idea/runConfigurations です。ただし、 .idea ディレクトリを共有したくない場合は、プロジェクト内の他のディレクトリに構成を保存できます。デフォルトでは無効になっており、PyCharm は実行構成設定を .idea/workspace.xml に保存します。

項目

説明

名前

実行構成の名前を指定して、編集または実行時に他の構成の間ですばやく識別できるようにします。

プロジェクトファイルとして保存

実行構成設定を含むファイルを保存して、他のチームメンバーと共有します。デフォルトの場所は .idea/runConfigurations です。ただし、 .idea ディレクトリを共有したくない場合は、プロジェクト内の他のディレクトリに構成を保存できます。

デフォルトでは無効になっており、PyCharm は実行構成設定を .idea/workspace.xml に保存します。

コード生成設定

項目	説明
Output Directory	生成されたファイルのディレクトリへのパス。
コードジェネレーター	コードジェネレーターの種類： OpenAPI ジェネレーター 7 OpenAPI ジェネレーター 6 OpenAPI ジェネレーター 5 OpenAPI ジェネレーター 4 Swagger コード生成 3 Swagger コード生成 2
言語	生成されたコードのターゲット言語。

項目

説明

Output Directory

生成されたファイルのディレクトリへのパス。

コードジェネレーター

コードジェネレーターの種類：

OpenAPI ジェネレーター 7
OpenAPI ジェネレーター 6
OpenAPI ジェネレーター 5
OpenAPI ジェネレーター 4
Swagger コード生成 3
Swagger コード生成 2

言語

生成されたコードのターゲット言語。

オプションを変更

一部の設定が非表示になっている場合は、オプションを変更をクリックして表示します。

項目	説明
Specification Path	OpenAPI 仕様へのパス。
Java ランタイム環境 (JRE)	Swagger Codegen の実行に使用する Java ランタイム
Custom Templates Path	Mustache テンプレート(英語)のあるディレクトリへのパス。

生成パラメーター

ターゲット言語に応じて構成パラメーターを指定します。詳細については、 swagger-codegen/README.md(英語) を参照してください。

2026 年 6 月 1 日