Swagger Codegen の使い方

0 件のコメント

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

Swagger Codegen とは

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

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

インストール

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

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

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

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

    1
    2
    3
    4
    java -jar swagger-codegen-cli.jar generate ^
      -l nodejs-server ^
      -o nodejs-server
  2. スタブサーバーを起動

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

    1
    npm start
  3. APIにアクセス

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

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

    /api/openapi.yaml

    1
    2
    3
    4
    5
    ...(省略)...
    servers:
    ...(省略)...

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

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