Swagger-UIでプルダウンでYAMLファイルを切り替える (API_URLS)

概要

下記のように１つのサービスで複数のAPIが存在する場合、
定義書(yamlファイル)を１つのSwagger-UIで扱えないか調べたのでメモする。

例) サンプル
・① サービス運営API 
  ※ サービス運営側のスタッフがアクセスする管理用のAPI

・② 企業管理API
  ※ 契約企業のスタッフがアクセスする管理用のAPI

・③ 店舗管理API
  ※ 契約企業の各店舗のスタッフがアクセスする管理用のAPI

・④ フロントAPI
  ※ 一般ユーザーがアクセスするホームページやアプリ用のAPI

準備

Swagger-UIを使うため、docker-compose.yamlファイルを用意する。

docker-compose.yaml

version: '3'
services:
  # Swagger (API仕様書)
  swagger-company:
    image: swaggerapi/swagger-ui
    volumes:
      - ./service.yaml:/usr/share/nginx/html/service.yaml  # サービス運営API
      - ./company.yaml:/usr/share/nginx/html/company.yaml  # 企業管理API
      - ./shop.yaml:/usr/share/nginx/html/shop.yaml        # 店舗管理API
      - ./front.yaml:/usr/share/nginx/html/front.yaml      # フロントAPI
    environment:
      API_URL: service.yaml
    ports:
      - "8081:8080"

dockerコンテナを起動する。

$ docker-compose up -d

ブラウザでアクセスしてみる。

$ open http://localhost:8081

「company.yaml」に書き換えて「Explore」ボタンを押すと切り替えできるようです。

切り替えはできるが、YAMLファイルを知らないと使い難いですね（＾＾；）

各APIをプルダウンで切り替えできるようにする

ドキュメントを見てみると「URL」以外に「URLS」というものが存在するようです。
https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md

そこで、「API_URLS」を追加してみる。

docker-compose.yaml

version: '3'
services:
  # Swagger (API仕様書)
  swagger-company:
    image: swaggerapi/swagger-ui
    volumes:
      - ./service.yaml:/usr/share/nginx/html/service.yaml
      - ./company.yaml:/usr/share/nginx/html/company.yaml
      - ./application.yaml:/usr/share/nginx/html/application.yaml
      - ./front.yaml:/usr/share/nginx/html/front.yaml
    environment:
      API_URL: system.yaml
      API_URLS: '[{name: "サービス運営API ", url: "service.yaml"},{name: "企業管理API", url: "company.yaml"},{name: "店舗管理API", url: "shop.yaml"},{name: "フロントAPI", url: "front.yaml"}]'
    ports:
      - "8081:8080"

dockerコンテナを再起動してみるとプルダウンが表示されるようになりました。

$ docker-compose down
$ docker-compose up -d

※ URL入力がプルダウンに切り替わりました

※ 定義したURL一覧が表示されて簡単に切り替えられるようになりました

まとめ

知らないだけで、便利なパラメータがあるんですね...

以上