api
swagger

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

More than 1 year has passed since last update.


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

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


  • YAMLの読み込みがサポートされた


    • swaggerのspecの書式はJSONとYAMLの2種類が用意されているのですが、swagger-ui 2.xではJSONしかサポートされていなかったので、YAMLをJSONに変換して読み込ませる必要がありました



  • 見た目がガッツリ変わった


    • deprecatedとかが地味だったのがわかりやすく表現される様になりました




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

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

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


公式Dockerイメージが有る

https://hub.docker.com/r/swaggerapi/swagger-ui/

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