Augmented Usamimi

it { is_expected.to be_blog.written_by(izumin5210) }

JSON SchemaからStatusつきAPI Documentをつくる

JSON Schema × jdocでドキュメントをつくる

JSON Schemaとステータスコード

JSON Schema,本来はJSONのフォーマットを定義するものなので当然ステータスコードなんて入らない. Hyper Schemaにも入ってなさそう. しかし,QIita API V2のドキュメントを見ると明らかにステータスコードが入ってる.

f:id:izumin5210:20150116235143p:plain

200 OKとかならまだわかるけど,`204 No Content'とかも入ってる.

f:id:izumin5210:20150116235318p:plain

ドキュメントは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 OK201 Created204 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: POST201 Created
  • mediaType: "null"204 No Content
  • それ以外 → 200 OK

QiitaでJSON Schemaやjdoc使ってAPI作ってるとこの目で確認できてちょっとテンション上がった.Incrementsさん行ってみたい.