Swagger Codegen

これはSwagger Codegenプロジェクトであり、OpenAPI記述が与えられた場合、APIクライアントライブラリ（SDK生成）、サーバスタブ、ドキュメントを自動的に生成できます。

💚 貢献を希望される方は、ガイドラインおよび未解決タスクの一覧を参照してください。💚

📔 詳細については、WikiページおよびFAQを参照してください。📔

⚠️ OpenAPI記述またはSwaggerファイルが信頼できないソースから取得されたものである場合は、Swagger Codegenを使用してAPIクライアント、サーバスタブ、またはドキュメントを生成する前に成果物を確認してください。コードインジェクションが発生する可能性があります。 ⚠️

バージョン管理

⚠️ このドキュメントはバージョン3.Xを参照しており、2.Xについてはこちらを確認してください。

Swagger Codegenの2.Xバージョンと3.Xバージョンの両方が利用可能で、それぞれ独立して保守されています。

注意

バージョン2.X (io.swagger) と 3.X (io.swagger.codegen.v3) は異なるグループIDを持っています。
OpenAPI 3.0.X は 3.X バージョンのみサポートされています。

完全なバージョン情報については、バージョン管理ドキュメントを参照してください。

サポートされている言語とフレームワーク

サポートされている言語/フレームワークの概要を以下に示します。

API クライアント: 「csharp」、「csharp-dotnet2」、「dart」、「go」、「java」、「javascript」、「jaxrs-cxf-client」、「kotlin-client」、「php」、「python」、「r」、「ruby」、「scala」、「swift3」、「swift4」、「swift5」、「typescript-angular」、「typescript-axios」、「typescript-fetch」
サーバスタブ: 「aspnetcore」、「go-server」、「inflector」、「java-vertx」、「jaxrs-cxf」、「jaxrs-cxf-cdi」、「jaxrs-di」、「jaxrs-jersey」、「jaxrs-resteasy」、「jaxrs-resteasy-eap」、「jaxrs-spec」、「kotlin-server」、「micronaut」、「nodejs-server」、「python-flask」、「scala-akka-http-server」、「spring」
APIドキュメントジェネレーター: 「dynamic-html」、「html」、「html2」、「openapi」、「openapi-yaml」

サポートされている言語/フレームワークの完全なリアルタイムリストを取得するには、オンラインジェネレーターAPIを直接クエリするか、cURLコマンドを使用できます。

1
curl -X 'GET' \
2
  'https://generator3.swagger.io/api/client/V3' \
3
  -H 'accept: application/json'

OpenAPI プロジェクトに関する追加情報については、OpenAPI 仕様をご覧ください。

互換性

OpenAPI 仕様は、2010年の最初の作成以来3回の改訂が行われました。Swagger Codegen プロジェクトの現在の安定版バージョンは、OpenAPI 仕様と以下の互換性があります。

Swagger Codegenバージョン	リリース日	Swagger / OpenAPI 仕様の互換性	備考
3.0.68 (現在の安定版)	2025-03-05	1.0, 1.1, 1.2, 2.0, 3.0	タグ v3.0.68
2.4.45 (現在の安定版)	2025-06-08	1.0, 1.1, 1.2, 2.0	タグ v2.4.45

💁 今後の展望も紹介します。

Swagger Codegenバージョン	リリース日	Swagger / OpenAPI 仕様の互換性	備考
3.0.69-SNAPSHOT（現在の3.0.0、次期マイナーリリース） SNAPSHOT	未定	1.0, 1.1, 1.2, 2.0, 3.0	マイナーリリース
2.4.46-SNAPSHOT（現在のマスター、次期マイナーリリース） SNAPSHOT	未定	1.0, 1.1, 1.2, 2.0	マイナーリリース

すべてのバージョンの詳細な内訳については、完全な互換性リストを参照してください。

はじめに

Swagger Codegen を使い始めるには、以下のガイドと手順を確認してください。

環境がセットアップできたら、クライアントやサーバの生成を開始する準備が整いました。

簡単な例として、Swagger Petstore の PHP クライアントを生成するには、以下を実行してください。

1
git clone https://github.com/swagger-api/swagger-codegen
2
cd swagger-codegen
3
git checkout 3.0.0
4
mvn clean package
5
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
6
   -i http://petstore.swagger.io/v2/swagger.json \
7
   -l php \
8
   -o /var/tmp/php_api_client

注意: Windows を使用している場合は、最後のコマンドを以下に置き換えてください。

1
java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l php -o c:\temp\php_api_client

JAR (最新リリース) は、maven.org から直接ダウンロードすることもできます。

利用可能な一般的なオプションのリストを取得するには、次を実行してください。

1
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate --help

PHP固有のオプション（-cオプションを介して設定ファイルでジェネレーターに渡すことができる）のリストを取得するには、次を実行してください。

1
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php

ジェネレータ

サンプルクライアントライブラリを生成するには

swagger サンプル petstore API に対してクライアントを構築するには、次の手順を実行します。

1
./bin/java-petstore.sh

Windows では、代わりに .\bin\windows\java-petstore.bat を実行します。

これにより、このコマンドでジェネレーターが実行されます。

1
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
2
  -i http://petstore.swagger.io/v2/swagger.json \                               # The location of the Swagger specifcation file (JSON/YAML).
3
  -l java \                                                                     # The desired language for the library.
4
  -o samples/client/petstore/java                                               # The output destination.

generate --help コマンドでオプションを取得できます（以下は部分的な結果のみを表示します）。

1
NAME
2
        swagger-codegen-cli generate - Generate code with chosen lang
3

4
SYNOPSIS
5
        swagger-codegen-cli generate
6
                [(-a <authorization> | --auth <authorization>)]
7
                [--additional-properties <additional properties>...]
8
                [--api-package <api package>] [--artifact-id <artifact id>]
9
                [--artifact-version <artifact version>]
10
                [(-c <configuration file> | --config <configuration file>)]
11
                [-D <system properties>...] [--git-repo-id <git repo id>]
12
                [--git-user-id <git user id>] [--group-id <group id>]
13
                [--http-user-agent <http user agent>]
14
                (-i <spec file> | --input-spec <spec file>)
15
                [--ignore-file-override <ignore file override location>]
16
                [--import-mappings <import mappings>...]
17
                [--instantiation-types <instantiation types>...]
18
                [--invoker-package <invoker package>]
19
                (-l <language> | --lang <language>)
20
                [--language-specific-primitives <language specific primitives>...]
21
                [--library <library>] [--model-name-prefix <model name prefix>]
22
                [--model-name-suffix <model name suffix>]
23
                [--model-package <model package>]
24
                [(-o <output directory> | --output <output directory>)]
25
                [--release-note <release note>] [--remove-operation-id-prefix]
26
                [--reserved-words-mappings <reserved word mappings>...]
27
                [(-s | --skip-overwrite)]
28
                [(-t <template directory> | --template-dir <template directory>)]
29
                [--type-mappings <type mappings>...] [(-v | --verbose)]
30

31
OPTIONS
32
        -a <authorization>, --auth <authorization>
33
            adds authorization headers when fetching the swagger definitions
34
            remotely. Pass in a URL-encoded string of name:header with a comma
35
            separating multiple values
36

37
...... (results omitted)
38

39
        -v, --verbose
40
            verbose mode

その後、クライアントをコンパイルして実行し、ユニットテストも実行できます。

1
cd samples/client/petstore/java
2
mvn package

他の言語にもペットストアのサンプルがあります。

1
./bin/android-petstore.sh
2
./bin/java-petstore.sh
3
./bin/objc-petstore.sh

サーバーからライブラリを生成する

それも同様に簡単です。-i フラグを使用して、サーバーまたはファイルを指定するだけです。

🔧 Swagger Codegen は、コード生成の好みをサポートするために多くの柔軟性を提供します。ジェネレーターのドキュメントをチェックして、いくつかの可能性とローカルファイルから生成する方法について学んでください。

選択的生成

プロジェクト内のすべてのモデルを生成したくない場合があります。同様に、1つか2つのAPIだけを書き込みたい場合や、特定のファイル形式を無視したい場合もあります。その場合は、選択的生成の指示を確認してください。

高度なジェネレーターのカスタマイズ

コードジェネレーターをカスタマイズするには、テンプレートの作成や変更だけでなく、さまざまな側面があります。各言語には、異なる型マッピングを処理したり、独自のモデルを導入したりするためのサポート構成ファイルがあります。詳細については、高度な構成ドキュメントを参照してください。

OpenAPI記述の検証

オプションがあります。最も簡単な方法は、オンラインバリデータを使用することです。これにより、OpenAPIファイルを検証できるだけでなく、デバッグフラグを使用すると、ファイルに何が問題があるかを確認できます。Swagger Validatorをチェックして、petstoreの例を検証してください。

独自のマシンで直接検証したい場合は、Spectralが優れたオプションです。

動的HTML APIドキュメントの生成

これを行うには、仕様ファイルを読み込む際に-l dynamic-htmlフラグを使用するだけです。これにより、AJAXを利用した単一ページアプリケーションとして利用可能なHTMLドキュメントが作成されます。ドキュメントを表示するには、

1
cd samples/dynamic-html/
2
npm install
3
node .

これにより、AJAX呼び出しが処理される場所としてnode.jsサーバーが起動します。

ワークフロー統合

Swagger Codegenを、お好みのCI/CDワークフロー内で直接活用することで、自動生成要件を効率化できます。Maven、Gradle、GitHubとの統合オプションに関する情報は、ワークフロー統合ガイドをご覧ください。🚀

オンラインジェネレーター

独自のコード生成インスタンスを実行・ホストしたくない場合は、オンラインジェネレーターの情報をご確認ください。

貢献

このページを参照してください。

🚧 swagger-codegen version 3のテンプレートとコード生成用のクラスは、swagger-codegen-generatorsリポジトリに移行中です。この移行プロセスについては、このページを参照してください。

セキュリティに関する連絡先

セキュリティ関連の問題や脆弱性については、公開されている課題追跡システムを使用するのではなく、security@swagger.io までメールでご連絡ください。

ありがとうございます

💚💚💚 問題提起、バグ修正、テンプレート作成、他者にとって有益なコンテンツ作成など、Swagger Codegenに貢献してくださったすべての方々に心より感謝申し上げます。💚💚💚