prmdを利用して空のレスポンスを表現する

prmdで生成されるドキュメントは、Response Exampleが自動的に生成されて便利。

しかし、何かを作成するときや何かを削除するときなど、レスポンスボディがなくても問題ないことを表すのが面倒。

prmd/link.md.erb at 928d9cb1c0fa1163bab5f3cb43c81eed4a147aa2 · interagent/prmd を読んで、どのようにResponse Exampleが生成されるかを調べて、空のレスポンスを表現する方法を調べてみた。

方法1: relをemptyにする

これが一番手っ取り早いけど、status codeが202に決め打ちになっている。

方法2: response_example を使う

次のようにresponse_exampleを指定するとResponse Examnpleをカスタマイズできる。若干面倒だけど現状ではこれしか方法がないように見える。

links:
- description: ユーザフォロー API
  href: "/api/user/{(%2Fschemata%2Fuser%23%2Fdefinitions%2Fid)}/follow"
  method: POST
  rel: create
  title: ユーザフォロー API
  schema:
    properties:
      access_token:
        "$ref": "/schemata/session#/definitions/access_token"
    required:
      - access_token
    type: object
  response_example:
    head: HTTP/1.1 201 Created
    body: ''