OpenAPIの3.0.0が出てた

1週間くらい前にリリースされていた模様。semverになってる。

github.com

気になるとこ

レスポンス深い

https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v3.0 などの例をちらっと見た程度だけど、以下のようにレスポンスの書き方がやや深くなって、contentとかレスポンス形式をキーに持つようになっていた。多くの場合はapplication/jsonだと思うので省略したいように思うけど、どうやら省略することはできないっぽい。ちなみにapplication/jsonキーの値にあたるものをMedia Type Objectと呼ぶ。

get:
  responses:
    200:
      description: pet response
      content:
        application/json:
          schema:
            type: array

Components Object

Components Objectなるものが増えていた。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject

これまで再利用したいオブジェクトはルートレベルにだらっと書かれていたけど、これらをまとめるような役割。

Server Object

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject

servers:
  - url: https://sandbox.example.com/v1
    description: Sandbox server
  - url: https://example.com/v1
    description: Production server

これまではトップレベルあたりにhostというキーでIPやホスト名を1個だけ書けるようになっていたけど、複数のホストが書けるようになっていた。このパスへのリクエストはこのサーバしか受け付けませんよ、みたいに書ける。

'/pets':
  get:
    ...
  servers:
    - url: https://example.com/v1  # $refが使えないように読めるのが気になる
      description: Production server

2.0からのコンバータとかは無いよね、ですよね。

追記

よくよく見たらCallback ObjectとLink Objectっていうよくわからないやつらも追加されていた。

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#callback-object

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#link-object

Link Objectはクライアントに対して、「レスポンスのこのパラメータ使えばこっちのAPIこんな風に叩けるんすよ」っていうことを示すものっぽい。

Callback Objectは全く使い方がわからない。わからない。