redoclyで作成したAPI仕様書からモックを作る

はじめに

API仕様書を作成する手段としてよく使われるものに、以下があると思います。

• API Blueprint + aglio
• Swagger
• redocly
• Excel
• PDF

昨年「API Blueprint + aglio」で作られたAPI仕様書をredoclyで作り直しました。

作り直した理由は以下です。

• 「API Blueprint + aglio」の仕様書の記法が好きではなかった
• YAMLを使ったAPI仕様書がイケイケな雰囲気になっている
• 「API Blueprint + aglio」の場合は、API仕様書を作成して終わり
• 「リクエストパラメタ一覧を書く + JSONのサンプルを書く」という手間が煩わしい

作り直す中で、便利だった機能なので紹介しようと思います。

この記事を見てredoclyを選択するきっかけになっていただけたらと思います。

注意

この記事では

• redoclyの使い方
• stoplight studioの使い方

などは説明しません。
ご注意ください。

完成品

OK

リクエスト

curl --request POST \
  --url http://localhost:4010/create \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: insomnia/8.6.1' \
  --data '{
        "title": "test",
        "content": "aaaa"
}'

レスポンス

{"result":true,"blog_id":1}

NG

リクエスト

curl --request POST \
  --url http://localhost:4010/create \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: insomnia/8.6.1' \
  --data '{
}'

レスポンス

{"result":false,"error_messages":["ブログタイトルは必須です","ブログ本文は必須です"]}

手順

１．nodeをインストールします
参考：　https://zenn.dev/shichi18/articles/20230325-01-50eb75b9096004
（API仕様書の作成時に、使うことになると思います）

２．Dockerを使えるようにします。

３．API仕様書を準備します
API仕様書は以下にサンプルを置いておきます。
ソース：　https://github.com/JunyaSatou/prism

４．prismを起動します

docker compose up prism-sample

さいごに

API仕様書は作って終わりではなく、API仕様書からモックを作れるので、
API仕様書の作成担当とAPIの実装担当が分かれている場合など、
クライアント側はAPIの実装を待たずして開発ができるので便利ですね。