Dockerを使ってswagger.yamlをサクッとみる (swagger-ui 3.x)

swagger-uiの3.xが出ました

個人的に大きく変わったなと思うポイントは、以下の二点です。

• YAMLの読み込みがサポートされた
  • swaggerのspecの書式はJSONとYAMLの２種類が用意されているのですが、swagger-ui 2.xではJSONしかサポートされていなかったので、YAMLをJSONに変換して読み込ませる必要がありました
• 見た目がガッツリ変わった
  • deprecatedとかが地味だったのがわかりやすく表現される様になりました

ローカルで動かすのが楽になった

以前こんな記事を書きました。

• SwaggerでAPIを定義してインタラクティブAPIドキュメントを見る
• Dockerを使ってswagger.yamlをサクッとみる

このときに比べてswagger周辺のツール群も洗練されてきたので、それに合わせてさくっと見る方法の最新版を書きます。

公式Dockerイメージが有る

Nginxでindex.htmlを表示するだけの簡単なものです。

$ docker run -p 8080:8080 swaggerapi/swagger-ui

これを利用する

上記index.htmlでは下記のように初期表示はpetstoreのAPI定義となっています。

index.html

  const ui = SwaggerUIBundle({
    url: "http://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

要するにここで指定されいるurl(=swagger specのURL)を任意の値に書き換えれば良いわけです。

ということで用意したのがこちらのdocker-compose定義です。

docker-compose.yaml

version: "2"
services:
  swagger:
    image: swaggerapi/swagger-ui
    volumes:
      - ./sample.yaml:/usr/share/nginx/html/sample.yaml
    environment:
      API_URL: sample.yaml
    ports:
      - "8080:8080"

ディレクトリ構造

.
├── docker-compose.yaml
└── sample.yaml

ポイントはこれだけです。

1. 自分で書いたswagger定義をsample.yamlとして置く
2. sedコマンドでindex.htmlのurlを書き換える

2のurl文字列の置換は、公式Dockerイメージに含まれるこのdocker-run.shで、API_URLという環境変数の値に置換されるようになっています。これに従い、docker-compose.yamlに環境変数API_URLを指定します。

そして、下記で起動すれば http://localhost:8080 でswaggerドキュメントを見ることができるでしょう。

$ docker-compose up