Open4

OpenAPIで仕様書を書くためのDocker環境を作る

Koji KobayashiKoji Kobayashi

OpenAPIの仕様書を1ファイルで書いているやついねえよなああ。
ということで

ファイルを分割して書いていきたい。
swagger-uiで確認したりフロントエンドのクライアント自動生成に使うので最終的には1ファイルにmergeしたい。
mergeは変更を自動的に検知して行ってほしい。

以上の要件を満たせるようにDockerで環境を作りたいと思いまーす。
ちなみにDockerfileやdocker-composeを使用した経験はありますが、きちんと最初から構築したことはほとんどないです。

Koji KobayashiKoji Kobayashi

docker composeで開発環境を作るとなると
RailsとかDBの構成を書いてあるdocker-compose.yamlがあると思いますが、特別ずっと起動していなければならないものではないので、docker-compose.openapi.yamlを作成してファイル指定で起動できるようにします。

docker compose -f docker-compose.openapi.yaml up

のような感じで起動できる。

Koji KobayashiKoji Kobayashi

RailsApp
├ app/
...
├ docker/swagger-merger/Dockerfile
├ docs/
...
├ docker-compose.openapi.yaml
├ docker-compose.yaml
...
こんな感じのファイル構造

docker-compose.openapi.yaml
version: "3"
services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    container_name: "swagger-ui"
    ports:
      - "8888:8080"
    volumes:
      - ./docs:/usr/share/nginx/html/docs
    environment:
      - URL=./docs/openapi.yml

  swagger-merger:
    build:
      dockerfile: ./docker/swagger-merger/Dockerfile
    command: >
      watch 'swagger-merger -i /docs/src/index.yaml -o /docs/openapi.yaml' /docs/src/
    volumes:
      - ./docs:/docs

swagger-uiの方の指定はこれで動いたのでこうしています。
volumesあたりの指定はリンクの記事のままだとうまく動かなかったので変更しています。

/usr/share/nginx/html/がswagger-uiのルートになっているようなのでそこにopenapi.ymlを置いてあげて
environment URL の部分で指定してあげるとみられるようになりました。

docker/swagger-merger/Dockerfile
FROM node:alpine

RUN npm install -g swagger-merger watch

CMD ["swagger-merger"]

こちらは記事の通りそのままです。