基本構造

OpenAPI の定義は YAML または JSON で記述できます。このガイドでは YAML の例のみを使用しますが、JSON も同様に機能します。YAML で記述された OpenAPI 3.0 定義の例は次のようになります。

1
openapi: 3.0.4
2
info:
3
  title: Sample API
4
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
5
  version: 0.1.9
6

7
servers:
8
  - url: http://api.example.com/v1
9
    description: Optional server description, e.g. Main (production) server
10
  - url: http://staging-api.example.com
11
    description: Optional server description, e.g. Internal staging server for testing
12

13
paths:
14
  /users:
15
    get:
16
      summary: Returns a list of users.
17
      description: Optional extended description in CommonMark or HTML.
18
      responses:
19
        "200": # status code
20
          description: A JSON array of user names
21
          content:
22
            application/json:
23
              schema:
24
                type: array
25
                items:
26
                  type: string

すべてのキーワード名は大文字と小文字が区別されます。

メタデータ

すべての API 定義には、この定義が基づいている OpenAPI Specification のバージョンを含める必要があります。

1
openapi: 3.0.4

OpenAPI バージョンは、API 定義の全体的な構造 (何をどのように文書化できるか) を定義します。OpenAPI 3.0 は、3 部構成のバージョン番号を持つセマンティックバージョニングを使用します。利用可能なバージョンは 3.0.0、3.0.1、3.0.2、3.0.3、3.0.4 で、機能的には同じです。

info セクションには、API 情報 (title、description (オプション)、version) が含まれます。

1
info:
2
  title: Sample API
3
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
4
  version: 0.1.9

title は API の名前です。description は API に関する詳細情報です。複数行に対応しており、リッチテキスト表現のために Markdown の CommonMark 方言をサポートしています。HTML は CommonMark が提供する範囲でサポートされています (CommonMark 0.27 Specification のHTML Blocks を参照)。version は API のバージョンを指定する任意の文字列です (ファイルのリビジョンや openapi バージョンと混同しないでください)。major.minor.patch のようなセマンティックバージョニング、または 1.0-beta や 2017-07-25 のような任意の文字列を使用できます。info は、連絡先情報、ライセンス、利用規約、その他の詳細のための他のキーワードもサポートしています。

参照: 情報オブジェクト。

サーバー

servers セクションでは、API サーバーとベース URL を指定します。本番環境やサンドボックスなど、複数のサーバーを定義できます。

1
servers:
2
  - url: http://api.example.com/v1
3
    description: Optional server description, e.g. Main (production) server
4
  - url: http://staging-api.example.com
5
    description: Optional server description, e.g. Internal staging server for testing

すべての API パスはサーバー URL を基準とします。上記の例では、/users は使用するサーバーに応じて http://api.example.com/v1/users または http://staging-api.example.com/users を意味します。詳細については、API サーバーとベースパスを参照してください。

パス

paths セクションでは、API 内の個々のエンドポイント (パス) と、これらのエンドポイントでサポートされる HTTP メソッド (操作) を定義します。たとえば、GET /users は次のように記述できます。

1
paths:
2
  /users:
3
    get:
4
      summary: Returns a list of users.
5
      description: Optional extended description in CommonMark or HTML
6
      responses:
7
        "200":
8
          description: A JSON array of user names
9
          content:
10
            application/json:
11
              schema:
12
                type: array
13
                items:
14
                  type: string