Swagger Codegen の使い方

今回は「Swagger Codegen の使い方」についてまとめます。 インストールからソースコード生成、動作確認までの一連操作を自PC上で行う場合の手順をまとめています。

Swagger Codegen とは

Swagger Codegen とは「OpenAPI Specificatioinに従って記述されたAPI仕様書を元に、ソースコードを生成するツール」です。 Swagger Editor, UI とともによく使われるツールになります。

Web上で出力もできますし、Dockerを利用した出力方法もありますが…今回は純粋に自端末で出力する方法をまとめます。

インストール

ツール自体に明示的なインストーラーも存在しないので必要なファイルをダウンロードするだけです。 前提として Java が必要なので、あらかじめ Java はダウンロード & インストールが必要です。

1. あらかじめ java をインストールしておく

   • Javaダウンロード

2. リポジトリから直接 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>

OpeｎAPI 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のサーバーサイドコードを生成して実際に動作させてみます。 リファレンスにもありますが…あくまで「スタブ」の扱いですね。 これをベースに開発…はちょっと難しそうかも、と個人的には思いました。

1. Node.jsサーバーサイドソースコードの生成

   以下のコマンドを実行してスタブを生成します。 今回は Swagger でよく利用される PetStore API の仕様を利用しました。

   java -jar swagger-codegen-cli.jar generate ^
     -i https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml ^
     -l nodejs-server ^
     -o nodejs-server
   

2. スタブサーバーを起動

   コマンドプロンプトを立ち上げて以下のコマンドを実行します。 Node.jsだと、通常は npm install をしてから実行になるのですが、あらかじめ package.json に npm install が仕込まれているので、いきなり npm start で起動できます。

   npm start
   

3. APIにアクセス

   ブラウザを起動して以下のURLにアクセスします。 デフォルトだと 8080 ポートでリッスンしているので、 localhost の 8080 へアクセスします。 普通に "/"(ルート) にアクセスしてもAPIは存在せずエラーになるので、"/docs" へアクセスします。 "/docs" にアクセスすると Swagger UI と同じ画面が表示されますので、この画面からAPIを実行して動作確認を行います。

   http://localhost:8080/docs
   

   

   PetStore API の場合、デフォルトで localhost へのサーバー設定が存在しないので必要に応じてサーバー設定を追加してあげるとよいです。

   /api/openapi.yaml

   ...(省略)...
   servers:
   - url: http://petstore.swagger.io/v1
   - url: http://localhost:8080               # ←追記
   ...(省略)...
   

今回は「Swagger Codegen の使い方」についてまとめました。 参考になったでしょうか？ 本記事がお役に立っていると嬉しいです！！

最後に… このブログに興味を持っていただけた方は、 ぜひ 「Facebookページ に いいね！」または 「Twitter の フォロー」 お願いします！！

• Facebook ページ
• twitter