へっぽこプログラマーの備忘録

プログラムを中心とした個人的なメモ用のブログです。 タイトルは迷走中。
内容の保証はできませんのであしからずご了承ください。
Home › Swagger › OpenAPI + Swagger + Redoc + GitLab Pages で API ドキュメントを管理する

2022/05/24

OpenAPI + Swagger + Redoc + GitLab Pages で API ドキュメントを管理する

event_note2022/05/24 0:31

APIドキュメントを簡単に作成・閲覧できるようにしたいと思い、OpenAPI で作成、Swagger および Redoc で表示、GitLab Pages で公開までを行いました。

概要

  • OpenAPI で yaml を作成
  • GitLab CI/DC により自動で Swagger および Redoc でビルドし、GitLab Pages に公開
  • ローカル環境用に Swagger および Redoc を Docker で動かす

ディレクトリ構造

今回試しに作成したファイル一式は以下となります。 詳細は後述します。

$ tree -a
.
├── .gitlab-ci.yml
├── README.md
├── docker-compose.yml
├── openapi
│   └── openapi.yaml
└── public
    └── index.html

OpenAPI の yaml を作成

Open API Specification (OAS) は REST API の仕様を記述するフォーマットです。 記述方法についてはググったらたくさん出てくるので割愛します。

例えば、以下のような yaml を作成します。

openapi: 3.0.0
info:
  version: 1.0.0
  title: OpenAPI Sample
paths:
  /users:
    get:
      summary: Get Users
      responses:
        '200':
          description: OK

ローカル環境の作成

ひとまず GitLab は置いておき、まずはローカル環境で Swagger および Redoc が動くようにしてみます。
３つのサービスを動かしたかったので、docker-compose 使いました。
作成した docker-compose.yml は以下です。

version: '3'
services:
  # エディター
  swagger-editor:
    image: swaggerapi/swagger-editor
    ports:
      - "8081:8080"
  # ビューワー（Swagger-UI 版）
  swagger-ui:
    image: swaggerapi/swagger-ui
    volumes:
      - ./openapi:/usr/share/nginx/html/openapi
    environment:
      API_URL: ./openapi/openapi.yaml # Swagger UIの画面を開いたときに初期値として表示するファイル
    ports:
      - '8082:8080'
  # ビューワー（Redoc 版）
  redoc:
    image: redocly/redoc
    volumes:
      - ./openapi:/usr/share/nginx/html/openapi
    environment:
      SPEC_URL: ./openapi/openapi.yaml # Redocの画面を開いたときに初期値として表示するファイル
      PORT: 8080 # nginx port(default:80)
    ports:
      - '8083:8080'

特に難しいところはないかと思います。
docker-compose up で動かしたあと、ブラウザでアクセスすればOKです。

http://localhost:8081 で Swagger Editor にアクセスして編集が行えます。
http://localhost:8082 で Swagger UI での表示を確認できます。
http://localhost:8083 で Redoc での表示を確認できます。

ただ、Swagger Editor は別にいらなかったかもしれません。
私の場合、結局 VSCode で yaml を編集し、ブラウザの表示を更新して確認、ってやってます。

閲覧に関しては Swagger より Redoc のほうが個人的に見やすいですね。

GitLab Pages で公開する

ローカルでの環境は以上で整ったので、次は GitLab に push したら自動ビルドを行って GitLab Pages に公開するように設定します。
GitLab Pages や GitLab CI/CD については割愛します。

Swagger + GitLab Pages については以下のページが参考になりました。

ただ、今回 swagger-ui-dist のバージョンを上げたので、sed コマンドで修正するファイルを index.html から swagger-initializer.js に変更する必要がありました。
これについては以下のページが参考になりました。

Redoc + GitLab Pages については以下のページが参考になりました。

以上の２つを組み合わせ、最終的に作成した .gitlab-ci.yml は以下です。
Swagger と Redoc のそれぞれで閲覧できるようにディレクトリを分けてみました。
プロキシ環境下でなければプロキシ関係の設定は不要です。

image: node:18-alpine

variables:
  # プロキシサーバー
  PROXY: 'http://example:8080'
  # ドキュメントのあるディレクトリ
  DOCS_FOLDER: "swagger"
  # ドキュメントファイル
  SPEC_TO_DISPLAY: "openapi.yaml"
  # デプロイ先
  DEPLOY_SWAGGER: "public/swagger"
  DEPLOY_REDOC: "public/redoc"

cache:
  paths:
    - ./node_modules

pages:
  stage: deploy
  before_script:
    # プロキシ環境下での下準備
    - npm -g config set proxy $PROXY
    - npm -g config set https-proxy $PROXY
    - npm -g config set registry http://registry.npmjs.org/
    - npm config set strict-ssl false
    # Swagger UI
    - npm install swagger-ui-dist@4.11.1
    # Redoc
    - npm install -g redoc-cli@0.13.14
  script:
    - mkdir -p $DEPLOY_SWAGGER
    - mkdir -p $DEPLOY_REDOC
    # Swagger UI
    - cp -rp node_modules/swagger-ui-dist/* $DEPLOY_SWAGGER
    - cp -rp $DOCS_FOLDER/* $DEPLOY_SWAGGER
    - sed -i "s#https://petstore\.swagger\.io/v2/swagger\.json#$SPEC_TO_DISPLAY#g" $DEPLOY_SWAGGER/swagger-initializer.js
    # Redoc
    - redoc-cli build -o $DEPLOY_REDOC/index.html $DOCS_FOLDER/$SPEC_TO_DISPLAY
  artifacts:
    paths:
      - public
  only:
    - main

ちなみに、Swagger の yaml ファイルは GitLab 上で Swagger でプレビュー表示されるので、外部に公開する必要がなければこれで十分かもしれません。

参考 URL

tweet facebook Pocket B!はてブ LINE