JSON SchemaからStatusつきAPI Documentをつくる
JSON Schema × jdocでドキュメントをつくる
JSON Schemaとステータスコード
JSON Schema,本来はJSONのフォーマットを定義するものなので当然ステータスコードなんて入らない. Hyper Schemaにも入ってなさそう. しかし,QIita API V2のドキュメントを見ると明らかにステータスコードが入ってる.
200 OK
とかならまだわかるけど,`204 No Content'とかも入ってる.
ドキュメントはjdocの生成コードにそっくりなので,JSON Schemaを利用しているはず…
とりあえず実装読んでみた.
読む
<%# template.md.erb#L49 %> HTTP/1.1 <%= link.response_status %> <%= "Content-Type: application/json" if link.has_response_body? -%> <%= "\n#{link.response_body}\n" if link.has_response_body? -%>
Jdoc::Link#response_status
を見てみる.
# lib/jdoc/link.rb#L164 def response_status case when method == "POST" 201 when has_response_body? 200 else 204 end end
200 OK
,201 Created
,204 No Content
を出せるらしい.
has_response_body?
どこや.
# lib/jdoc/link.rb#L153 def has_response_body? @raw_link.media_type != "null" end
media_type
をnullにしたらいいらしい.
- description: 特定の投稿をストックしている場合に204を返します。 href: "/api/v2/items/:item_id/stock" method: PUT rel: empty mediaType: "null" targetSchema: additionalProperties: false type: - object
なるほど.
まとめ
method: POST
→201 Created
mediaType: "null"
→204 No Content
- それ以外 →
200 OK
QiitaでJSON Schemaやjdoc使ってAPI作ってるとこの目で確認できてちょっとテンション上がった.Incrementsさん行ってみたい.