概要

openAPIを使ってAPIドキュメントを作成したのでやったことを軽くまとめた。
Swagger Editorを使って1つのファイルにまとめて書いてもよかったが、エンドポイント2つの時点で100行超えるのでファイル分は必須だと感じた。

docker-compose.ymlについて

/modelsに書かれた内容をswagger.ymlにまとめてswagger-uiに表示するようにした。

version: "3.3"
services:
  # swagger.yml更新
  swagger-merger:
    build:
      context: .
      dockerfile: ./Dockerfile
    volumes:
      - ./models:/models
      - ./open_api.yml:/open_api.yml
      - './swagger.yml:/swagger.yml'
    command:
      # open_api.ymlの`$ref`を全てマージしたものを`swagger.yml`にコピーする
      swagger-merger -i open_api.yml

  # swagger表示
  swagger-ui:
    image: swaggerapi/swagger-ui
    volumes:
      - './swagger.yml:/usr/share/nginx/html/swagger.yml'
    environment:
      API_URL: swagger.yml
    ports:
      - '8080:8080'
    # swagger-mergerでswagger.ymlを更新してから立ち上げる
    depends_on:
      - "swagger-merger"
# コンテナ間でswagger.ymlを共有
volumes:
  swagger.yml:
    driver: local

詰まったところ

`swagger-merger`のコマンドを勘違いしていた

swagger-mergerのコマンドのオプションで-iと-oがある。
-iに$refで省略した元のファイルを書いて、-oに$refの中身を書くのかと勘違いしており結構時間がかかってしまった。

-iの方に書かれた$refは勝手に展開してくれた。

dockerのコンテナ間でのファイル共有

シンプルにdockerの経験不足。
今回depends_onで他のコンテナの起動を待つことと直下のvolumesでファイル共有できることを知った。
あまりdockerfileをいじる機会がなかったのでいい勉強になった。

追記(2021/04/19)

モックサーバーを立ち上げる記事を書きました。
この記事の続きになってますので宜しければ一読いただけると嬉しいです。

github