初めて OpenAPI で API と Webhook の仕様書を書いてみた
最近、初めて OpenAPI を使って API と Webhook の仕様書を書いてみました。初めての経験だったので、調べながら進めましたが、その際の学びや気づきを備忘録としてまとめておきます。同じように OpenAPI に挑戦する人の参考になれば幸いです。
使用ツール：Swagger Editor
仕様書を作成する際に使用したのは Swagger Editor です。このツールは、リアルタイムで変更が反映される上に、エラー箇所もハイライトしてくれるので、とても便利でした。
ただし、いくつか問題もありました。特に「改行」がそのまま反映されず、HTML の <br/> タグを使わないと改行ができない点です。これは Swagger Editor の仕様なのか、他のツールでも共通なのかは分かりませんが、少し不便に感じました。その一方で、リストやテーブルは HTML で記述できたので、結果的には良かったと思います。
tags の扱いについて
API (paths) では tags を利用してエンドポイントをまとめられるのですが、Webhook には tags が反映されませんでした。Webhooks にも tags が使えるのかもっと調べる余地がありそうですが、今回は特に必要性を感じなかったので、一旦保留としました。
Webhooks と OpenAPI バージョンの関係
Webhooks を OpenAPI で表現するには、バージョン 3.1 以降が必要です。最初は OpenAPI 3.0 で書き始めましたが、Webhooks がサポートされていないことに気づき、急遽 OpenAPI 3.1 に切り替えることにしました。
GET パラメータでの連想配列の扱い
GET パラメータで連想配列を指定する方法が分からず、少し悩みました。PHP では param[key][]=value のように記述すると、key が確定していない配列でも自動でパースしてくれますが、これを OpenAPI で表現するのが難しかったです。
とりあえず type: array で param[key][] としてパラメータを定義してみましたが、UI 上で key を変更できないため、もっと良い方法があるかもしれません。引き続き調査が必要です。
allOf と enum の関係
allOf を使って enum を指定する際、元の値が上書きされず、追加されるということが分かりました。enum 以外の要素を先に定義し、その後 allOf で enum を追加すると、よりきれいに整理された仕様書を作成できることが分かりました。例えば以下のような形です：
Status:
type: string
description: ステータス
StatusSuccess:
allOf:
- $ref: '#/components/schemas/Status'
- enum:
- updated
- created
StatusError:
allOf:
- $ref: '#/components/schemas/Status'
- enum:
- not found
- validation error
認証ヘッダーの指定
Authorization ヘッダーは securitySchemes で指定することができます。例えば、Basic 認証の場合は以下のように記述します：
type: http
scheme: basic
また、独自の認証ヘッダーを設定したい場合は、次のように記述します：
type: apiKey
name: original-header
in: header
複数のタイプの指定
string | null のように複数の型を許可する場合、oneOf を使用します。例えば：
oneOf:
- type: string
- type: 'null'
nullable を指定する際には、型を 'null' と文字列として定義する必要があることも覚えておくと良いです。
以上、初めての OpenAPI での仕様書作成を通じて学んだポイントをまとめました。最初は戸惑う部分もありましたが、次回以降はもっとスムーズに書けるのではないかと思います。