今回は「Swagger Codegen の使い方」についてまとめます。 インストールからソースコード生成、動作確認までの一連操作を自PC上で行う場合の手順をまとめています。
Swagger Codegen とは
Swagger Codegen とは「OpenAPI Specificatioinに従って記述されたAPI仕様書を元に、ソースコードを生成するツール」です。 Swagger Editor, UI とともによく使われるツールになります。
Web上で出力もできますし、Dockerを利用した出力方法もありますが…今回は純粋に自端末で出力する方法をまとめます。
インストール
ツール自体に明示的なインストーラーも存在しないので必要なファイルをダウンロードするだけです。 前提として Java が必要なので、あらかじめ Java はダウンロード & インストールが必要です。
-
あらかじめ java をインストールしておく
-
リポジトリから直接 jar ファイルをダウンロード
以下のリンクから直接ダウンロードしてください。 ほかのバージョンが良い場合、バージョン番号を変更してブラウザなどで直接ダウンロードすればOKです。 公開されているバージョンについては Swagger Codegen の GitHub Readme.md を参照してください。
swagger-codegen-cli-3.0.19.jar
https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.19/swagger-codegen-cli-3.0.19.jar
コード生成
ダウンロードした jar を実行することでコード生成ができます。 以下のコマンドではダウンロードした jar ファイルについているバージョン名を削除した状態で実行しています。
java -jar swagger-codegen-cli.jar generate ^ -i <SPEC_FILE> ^ -l <LANGUAGE> ^ -o <OUTPUT_DIR>
-i <SPEC_FILE>
- OpenAPI Specification で記述されたAPI仕様ファイルを指定します。 ローカルのファイルでも良いし、インターネット上のファイル(URL)でも良いです。
-l <LANGUAGE>
-
出力したいソースコードの種類を指定します。
指定できる値は以下のようなものがあります(一部抜粋)。
値 種類 説明 aspnetcore
サーバー ASP.NET Core 1.0 go-server
サーバー Go Server jaxrs-resteasy
サーバー Java JAX-RS (Resteasy) spring
サーバー Java SpringBoot nodejs-server
サーバー Node.js csharp
クライアント C# java
クライアント Java javascript
クライアント JavaScript swift5
クライアント Swift 5 kotlin-client
クライアント Kotlin openapi
その他 OpenAPI Specification (JSON) openapi-yaml
その他 OpenAPI Specification (YAML) -o <OUTPUT_DIR>
- 出力先ディレクトリ名を指定します。
生成したサーバーサイドコードの動作確認
Node.jsのサーバーサイドコードを生成して実際に動作させてみます。 リファレンスにもありますが…あくまで「スタブ」の扱いですね。 これをベースに開発…はちょっと難しそうかも、と個人的には思いました。
-
Node.jsサーバーサイドソースコードの生成
以下のコマンドを実行してスタブを生成します。 今回は Swagger でよく利用される PetStore API の仕様を利用しました。
1234java -jar swagger-codegen-cli.jar generate ^
-l nodejs-server ^
-o nodejs-server
-
スタブサーバーを起動
コマンドプロンプトを立ち上げて以下のコマンドを実行します。 Node.jsだと、通常は
npm install
をしてから実行になるのですが、あらかじめpackage.json
にnpm install
が仕込まれているので、いきなりnpm start
で起動できます。1npm start
-
APIにアクセス
ブラウザを起動して以下のURLにアクセスします。 デフォルトだと 8080 ポートでリッスンしているので、 localhost の 8080 へアクセスします。 普通に "/"(ルート) にアクセスしてもAPIは存在せずエラーになるので、"/docs" へアクセスします。 "/docs" にアクセスすると Swagger UI と同じ画面が表示されますので、この画面からAPIを実行して動作確認を行います。
PetStore API の場合、デフォルトで localhost へのサーバー設定が存在しないので必要に応じてサーバー設定を追加してあげるとよいです。
/api/openapi.yaml
12345
今回は「Swagger Codegen の使い方」についてまとめました。 参考になったでしょうか? 本記事がお役に立っていると嬉しいです!!
最後に… このブログに興味を持っていただけた方は、 ぜひ 「Facebookページ に いいね!」または 「Twitter の フォロー」 お願いします!!