初めて 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 での仕様書作成を通じて学んだポイントをまとめました。最初は戸惑う部分もありましたが、次回以降はもっとスムーズに書けるのではないかと思います。