Swagger Codegen

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

💚 貢献したい場合は、ガイドラインと未解決のタスクのリストを参照してください。💚

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

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

バージョン管理

⚠️ このドキュメントはバージョン 2.X を参照しています。3.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 クライアント: ActionScript、Ada、Apex、Bash、C# (.net 2.0、3.5 以降)、C++ (cpprest、Qt5、Tizen)、Clojure、Dart、Elixir、Elm、Eiffel、Erlang、Go、Groovy、Haskell (http-client、Servant)、Java (Jersey1.x、Jersey2.x、OkHttp、Retrofit1.x、Retrofit2.x、Feign、RestTemplate、RESTEasy、Vertx、Google API Client Library for Java、Rest-assured)、Kotlin、Lua、Node.js (ES5、ES6、Google Closure Compiler アノテーション付き AngularJS) Objective-C、Perl、PHP、PowerShell、Python、R、Ruby、Rust (rust、rust-server)、Scala (akka、http4s、swagger-async-httpclient)、Swift (2.x、3.x、4.x、5.x)、Typescript (Angular1.x、Angular2.x、Fetch、jQuery、Node)
サーバ・スタブ: Ada, C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-server), Scala (Finch, Lagom, Scalatra)
API ドキュメント生成ツール: HTML、Confluence Wiki
構成ファイル: Apache2
その他: JMeter

OpenAPI プロジェクトに関する追加情報については、OpenAPI-Spec をご確認ください。

互換性

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 を起動して実行するには、以下のガイドと手順を確認してください。

環境設定が完了したら、クライアントやサーバーの生成を開始する準備が整いました。

簡単な例として、https://petstore.swagger.io/v2/swagger.json の PHP クライアントを生成するには、以下を実行します。

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

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

1
java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar generate -i https://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 help generate

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 https://petstore.swagger.io/v2/swagger.json \
3
  -l java \
4
  -o samples/client/petstore/java

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

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 Spec を検証する

いくつかの選択肢があります。最も簡単な方法は、当社のオンラインバリデーターを使用することです。これにより、仕様を検証できるだけでなく、デバッグフラグを使用して仕様のどこが間違っているかを確認できます。例えば、Swagger Validatorをご覧ください。

自分のマシンで直接検証したい場合は、Spectralが優れた選択肢です。

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

そのために、スペックファイルを読み込む際に -l dynamic-html フラグを使用するだけです。これにより、AJAX を使用したシングルページアプリケーションとして利用できる HTML ドキュメントが作成されます。ドキュメントを表示するには、

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

これにより、AJAX 呼び出しの受け入れ先となる node.js サーバーが起動します。

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

そのために、仕様ファイルを読み込む際に -l html フラグを使用するだけです。これにより、埋め込み CSS を含む単一のシンプルな HTML ファイルが作成され、メールの添付ファイルとして送信したり、ファイルシステムから読み込んだりできます。

1
cd samples/html/
2
open index.html

ワークフロー統合

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

オンラインジェネレータ

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

貢献

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

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

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

ありがとうございました

💚💚💚 問題の提起、バグの修正、テンプレートの作成、他の人が利用できる有用なコンテンツの作成など、Swagger Codegen に貢献してくださった皆様に、心より感謝申し上げます。💚💚💚