redocでREST API仕様書作成

はじめに

業務では専らREST APIを実装しているのだが、仕様を書くのにWikiやSwaggerを利用していた。
ただ、WikiはAPI仕様書としてはやや書きづらい＆見栄えもよくない、Swaggerはプロジェクトが増えると有料になってしまう。。
ということがあり、いろいろと探し試した結果redocに落ち着いた。

インストール

以下などを参考にしインストール。
Using the Redoc CLI

使い方

redoc-cli serve hoge.yaml でHTTPサーバーになってくれる。
うちでは、redoc-cli bundle hoge.yaml -o hoge.html などでHTMLファイルに出力し、HTMLをS3経由で参照している。

オプション

以下のオプションで使っている。

redoc-cli bundle hoge.yaml --options.pathInMiddlePanel=true --options.disableSearch=true --options.hideDownloadButton=true --options.jsonSampleExpandLevel=all -o hoge.html

オプション名	概要
options.pathInMiddlePanel	右側のパネルではなく、中央パネルにパスを表示する。
options.disableSearch	検索ボックスを無効にする。
options.hideDownloadButton	ダウンロードボタンを非表示にする。
options.jsonSampleExpandLevel	JSONペイロードサンプルのデフォルトの展開レベルを設定する。allは全て展開。

その他のオプションは以下を参照。
redoc options object

書き方

記述はYAML。
"|"の後に改行して、Markdownで記述可能。
複数のファイルに分割してもOK。

hoge.yaml

openapi: 3.0.0
info:
  version: '1'
  title: 'Hoge API'
  description: |
    ## HOGE用 API Version 1

    HOGEで使用するAPI仕様です。

    ### フロー

    <img src="hoge.png" />

tags:
  - name: User
    description: ユーザー

components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Bearerスキーマのアクセストークン
  parameters:
    userAgentHeader:
      in: header
      name: User-Agent
      required: true
      schema: {type: string, enum: ['HOGE/1.0']}

paths:
  /hoge/user:
    $ref: ./hoge/user.yaml

servers:
  - description: Hoge Staging
    url: https://hoge-stg.example.com/v1
  - description: Hoge Production
    url: https://hoge.example.com/v1

hoge/user.yaml

# /hoge/user:
    get:
      tags: [User]
      summary: ユーザーの方取得
      description: |
        ユーザー情報を取得する。

      parameters:
        - $ref: '../hoge.yaml#/components/parameters/userAgentHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required: [id, name, email]
                properties:
                  id: {title: ユーザーID, type: integer, example: 128}
                  name: {title: ユーザー名, type: string, example: '山田 太郎'}
                  email: {title: メールアドレス, type: string, format: email, example: '[e-mail]'}
        '400':
          description: リクエストエラー
          content:
            application/json:
              schema: {type: object, required: [Error], properties: {Error: {title: エラーメッセージ, type: string}}}

最後に

YAMLをシコシコと書けばよく、Gitで管理することでバージョン管理が楽になった。
また、OpenAPIの仕様に則って記述することで、開発者間での共通化が図れ、誰が書いても同じような仕様書が出来上がる。
ただ、ラーニングコストが意外とかかる、細かい部分で融通がきかない（知見不足かもしれないが。。）というデメリットもある。

うちではGithubでバージョン管理しており、YAMLをPushした際にGithub Actionを用いて、HTML作成→S3にアップロードをやっている。
この話は次回にでも。。