swagger codegen
Swagger
これは Swagger Codegen プロジェクトで、OpenAPI 仕様を指定して API クライアント ライブラリ (SDK 生成)、サーバー スタブ、ドキュメントを自動的に生成できます。
貢献したい場合は、ガイドラインと未解決のタスクのリストを参照してください。
詳細については、Wiki ページと FAQ を参照してください。
⚠️ このドキュメントではバージョン 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 -クライアント、サーバント)、 Java (Jersey1.x、Jersey2.x、 OkHttp、Retrofit1.x、Retrofit2.x、Feign、RestTemplate、RESTEasy、Vertx、Java 用 Google API クライアント ライブラリ、安心)、 Kotlin 、 Lua 、 Node.js (ES5、ES6、Google Closure Compiler アノテーション付きAngularJS) -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) 、フェッチ、jQuery、ノード)
サーバー スタブ: 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 仕様の検証
動的 HTML API ドキュメントの生成
静的 HTML API ドキュメントの生成
ワークフローの統合
オンラインジェネレーター
貢献
Swagger Codegen コア チーム
OpenAPI 仕様は、2010 年に最初に作成されて以来 3 回改訂されています。Swagger Codegen プロジェクトの現在の安定バージョンには、OpenAPI 仕様と次の互換性があります。
| Swagger Codegen のバージョン | 発売日 | Swagger / OpenAPI 仕様の互換性 | 注意事項 |
|---|---|---|---|
| 3.0.62 (現在は安定しています) | 2024-08-27 | 1.0、1.1、1.2、2.0、3.0 | タグ v3.0.62 |
| 2.4.43 (現在安定) | 2024-08-09 | 1.0、1.1、1.2、2.0 | タグ v2.4.42 |
また、これから起こることの概要も以下に示します。
| Swagger Codegen のバージョン | 発売日 | Swagger / OpenAPI 仕様の互換性 | 注意事項 |
|---|---|---|---|
| 3.0.63-SNAPSHOT (現在の 3.0.0、今後のマイナー リリース) スナップショット | 未定 | 1.0、1.1、1.2、2.0、3.0 | マイナーリリース |
| 2.4.44-SNAPSHOT (現在のマスター、今後のマイナー リリース) スナップショット | 未定 | 1.0、1.1、1.2、2.0 | マイナーリリース |
すべてのバージョンの詳細な内訳については、完全な互換性リストを参照してください。
Swagger Codegen を起動して実行するには、次のガイドと手順を確認してください。
前提条件
建物
Docker の使用
環境をセットアップしたら、クライアントやサーバーの生成を開始する準備が整います。
簡単な例として、https://petstore.swagger.io/v2/swagger.json の PHP クライアントを生成するには、次のコマンドを実行します。
git clone https://github.com/swagger-api/swagger-codegencd swagger-codegen
mvnクリーンパッケージ
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar 生成
-i https://petstore.swagger.io/v2/swagger.json
-l php
-o /var/tmp/php_api_client注: Windows を使用している場合は、最後のコマンドを次のように置き換えます。
java -jar modulesswagger-codegen-clitargetswagger-codegen-cli.jar 生成 -i https://petstore.swagger.io/v2/swagger.json -l php -o c:tempphp_api_client
JAR (最新リリース) を maven.org から直接ダウンロードすることもできます。
利用可能な一般的なオプションのリストを取得するには、次のコマンドを実行します。
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar ヘルプ生成
PHP で指定されたオプションのリストを取得するには ( -cオプションを介して構成ファイルとともにジェネレーターに渡すことができます)、次を実行してください。
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
次のように、Swagger サンプル ペットストア API に対してクライアントを構築できます。
./bin/java-petstore.sh
(Windows では、代わりに.binwindowsjava-petstore.batを実行します)
これにより、次のコマンドでジェネレーターが実行されます。
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar 生成 -i https://petstore.swagger.io/v2/swagger.json -l java -o サンプル/クライアント/ペットストア/java
多くのオプションを備えています。 help generateコマンドを使用してオプションを取得できます (以下は部分的な結果のみを示しています)。
NAME
swagger-codegen-cli generate - Generate code with chosen lang
SYNOPSIS
swagger-codegen-cli generate
[(-a <authorization> | --auth <authorization>)]
[--additional-properties <additional properties>...]
[--api-package <api package>] [--artifact-id <artifact id>]
[--artifact-version <artifact version>]
[(-c <configuration file> | --config <configuration file>)]
[-D <system properties>...] [--git-repo-id <git repo id>]
[--git-user-id <git user id>] [--group-id <group id>]
[--http-user-agent <http user agent>]
(-i <spec file> | --input-spec <spec file>)
[--ignore-file-override <ignore file override location>]
[--import-mappings <import mappings>...]
[--instantiation-types <instantiation types>...]
[--invoker-package <invoker package>]
(-l <language> | --lang <language>)
[--language-specific-primitives <language specific primitives>...]
[--library <library>] [--model-name-prefix <model name prefix>]
[--model-name-suffix <model name suffix>]
[--model-package <model package>]
[(-o <output directory> | --output <output directory>)]
[--release-note <release note>] [--remove-operation-id-prefix]
[--reserved-words-mappings <reserved word mappings>...]
[(-s | --skip-overwrite)]
[(-t <template directory> | --template-dir <template directory>)]
[--type-mappings <type mappings>...] [(-v | --verbose)]
OPTIONS
-a <authorization>, --auth <authorization>
adds authorization headers when fetching the swagger definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
...... (results omitted)
-v, --verbose
verbose modeその後、クライアントをコンパイルして実行するだけでなく、それに対する単体テストも行うことができます。
cd サンプル/クライアント/ペットストア/java mvn パッケージ
他の言語にもペットストアのサンプルがあります。
./bin/android-petstore.sh ./bin/java-petstore.sh ./bin/objc-petstore.sh
これも同様に簡単です。 -iフラグを使用してサーバーまたはファイルを指定するだけです。
? Swagger Codegen には、コード生成設定をサポートするための非常に高い柔軟性が備わっています。ジェネレーターのドキュメントを確認して、いくつかの可能性を説明し、ローカル ファイルから生成する方法とファイル形式を無視する方法を紹介します。
プロジェクト内のすべてのモデルを生成したくない場合があります。 同様に、1 つまたは 2 つの API だけを記述したい場合もあります。その場合は、選択的生成手順を確認してください。
コード ジェネレーターのカスタマイズには、テンプレートの作成または変更だけでなく、さまざまな側面があります。 各言語には、さまざまなタイプのマッピングを処理したり、独自のモデルを使用したりするためのサポート構成ファイルがあります。詳細については、高度な構成ドキュメントを参照してください。
選択肢はあります。 最も簡単なのは、オンライン バリデーターを使用することです。これにより、仕様を検証できるだけでなく、デバッグ フラグを使用して、仕様のどこが間違っているかを確認できます。 たとえば、Swagger Validator をチェックしてください。
自分のマシン上で直接検証を行いたい場合は、Spectral が優れたオプションです。
これを行うには、仕様ファイルを読み取るときに-l dynamic-htmlフラグを使用するだけです。 これにより、AJAX を使用した単一ページのアプリケーションとして使用できる HTML ドキュメントが作成されます。 ドキュメントを表示するには:
cd サンプル/dynamic-html/ npmインストール ノード。
これにより、node.js サーバーが起動され、AJAX 呼び出しの行き先が確保されます。
これを行うには、仕様ファイルを読み取るときに-l htmlフラグを使用するだけです。 これにより、CSS が埋め込まれた単一の単純な HTML ファイルが作成されるため、電子メールの添付ファイルとして送信したり、ファイル システムからロードしたりできます。
cd サンプル/html/ インデックス.htmlを開く
好みの CI/CD ワークフロー内で Swagger Codegen を直接利用して、自動生成要件を合理化することができます。 Maven、Gradle、GitHub の統合オプションに関する情報については、ワークフロー統合ガイドをご覧ください。 ?
独自のコード生成インスタンスを実行およびホストしたくない場合は、オンライン ジェネレーター情報を確認してください。
こちらのページをご参照ください
Swagger Codegen のコア チーム メンバーは、定期的にプロジェクトに多大な貢献 (問題のレビュー、バグの修正、機能強化など) を行っている貢献者です。
コア チームのメンバーは次の責任を負います。
他のユーザーにガイダンスと指示を提供します
プルリクエストと問題をレビューする
機能強化、バグ修正、ドキュメントの更新によりジェネレーターを改善します。
ジェネレーターの技術的方向性を設定します
セキュリティ関連の問題や脆弱性がある場合は、公開の問題トラッカーを使用する代わりに、[email protected] に電子メールを送信して開示してください。
Swagger Codegen プロジェクトは、Swagger / Open API 仕様のユーザーへの特典を目的としています。 プロジェクト自体には、指定されたライセンスがあります。 また、以下の点をご了承ください。
このプロジェクトに含まれるテンプレートにはライセンスが適用されます。
生成されたコードは意図的に親プロジェクトのライセンスの対象外です
このプロジェクトからコードが生成された場合、コードは現状のままとみなされ、ソフトウェアのユーザーが所有するものとします。 生成されたコードには、明示的または黙示的を問わず、いかなる保証もありません。 自由に使用でき、生成後のコードはユーザーの責任となり、適切と思われるライセンス条項が適用されます。
問題の提起、バグの修正、テンプレートの作成、他の人が恩恵を受ける有益なコンテンツの作成など、Swagger Codegen に貢献してくださったすべての方々に大きな拍手を送りたいと思います。
