作ったOpenAPIのyamlからReDocを使ってドキュメント生成する方法

3742 ワード
OpenAPI ReDoc OpenAPI テキストリンク

はじめに

APIのドキュメントをプロジェクトで作成していく上でOpenApi 3を選択しました。
ローカルで見れるカタチに整形する方法としてReDocを使って見ようと思います。
※Open APIの作り方はこの記事では省略しています。

最終形のカタチ

bash
$ tree
.
├── app.html
└── openapi.yaml

サンプル Open API の準備

openapi.yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger sample
paths:
  /users:
    get:
      summary: Usersを取得するAPIです。
      responses:
        '200':
          description: HTTPステータスコード200と以下の情報を含むJSONオブジェクトを返します。
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: 1234567

ReDoc

  • インストール
bash
$ npm install -g redoc-cli
  • バンドル
bash
$ redoc-cli bundle openapi.yaml --output app.html
  • 作成ファイルをapp.html開く

最後に

すごく簡単に見れる状態にできました。
次はHTMLファイルをホストする環境を作りたいと思っています。

Dockerfile で環境もつくれるので記載しておきます。

Dockerfile
FROM node

RUN apt-get -y update

RUN npm i -g npm
RUN npm i -g redoc-cli