パスと操作

OpenAPI の用語では、パスは /users や /reports/summary/ など、API が公開するエンドポイント（リソース）であり、操作は GET、POST、DELETE など、これらのパスを操作するために使用される HTTP メソッドです。

パス

API のパスと操作は、API 仕様のグローバル paths セクションで定義されます。

1
paths:
2
  /ping: ...
3
  /users: ...
4
  /users/{id}: ...

すべてのパスは API サーバーの URL に対する相対パスです。完全なリクエスト URL は <server-url>/path として構築されます。グローバル servers は、パスレベルまたは操作レベルでオーバーライドすることもできます（詳細については以下を参照）。パスには、ドキュメント作成のためにオプションの短い summary と長い description を含めることができます。この情報は、このパス内のすべての操作に関連するものとします。description は複数行に対応し、リッチテキスト表現のためにMarkdown（CommonMark）をサポートしています。

1
paths:
2
  /users/{id}:
3
    summary: Represents a user
4
    description: >
5
      This resource represents an individual user in the system.
6
      Each user is identified by a numeric `id`.
7

8
    get: ...
9
    patch: ...
10
    delete: ...

パスのテンプレート化

中括弧 {} を使用して、URL の一部をパスパラメータとしてマークできます。

1
/users/{id}
2
/organizations/{orgId}/members/{memberId}
3
/report.{format}

API クライアントは、/users/5 や /users/12 などの API 呼び出しを行う際に、適切なパラメータ値を提供する必要があります。

操作

各パスについて、そのパスにアクセスするために使用できる操作（HTTP メソッド）を定義します。OpenAPI 3.0 は get、post、put、patch、delete、head、options、trace をサポートしています。単一のパスで複数の操作をサポートできます。たとえば、ユーザーのリストを取得するための GET /users と、新しいユーザーを追加するための POST /users などです。OpenAPI は、パスと HTTP メソッドの組み合わせとして一意の操作を定義します。これは、同じパスに対して 2 つの GET メソッドや 2 つの POST メソッドは許可されないことを意味します。たとえ異なるパラメータを持っていても（パラメータは一意性には影響しません）。以下は操作の最小限の例です。

1
paths:
2
  /ping:
3
    get:
4
      responses:
5
        "200":
6
          description: OK

以下は、パラメータとレスポンススキーマを含むより詳細な例です。

1
paths:
2
  /users/{id}:
3
    get:
4
      tags:
5
        - Users
6
      summary: Gets a user by ID.
7
      description: >
8
        A detailed description of the operation.
9
        Use markdown for rich text representation,
10
        such as **bold**, *italic*, and [links](https://swagger.dokyumento.jp).
11
      operationId: getUserById
12
      parameters:
13
        - name: id
14
          in: path
15
          description: User ID
16
          required: true
17
          schema:
18
            type: integer
19
            format: int64
20
      responses:
21
        "200":
22
          description: Successful operation
23
          content:
24
            application/json:
25
              schema:
26
                $ref: "#/components/schemas/User"
27
      externalDocs:
28
        description: Learn more about user operations provided by this API.
29
        url: http://api.example.com/docs/user-operations/
30

31
components:
32
  schemas:
33
    User:
34
      type: object
35
      properties:
36
        id:
37
          type: integer
38
          format: int64
39
        name:
40
          type: string
41
      required:
42
        - id
43
        - name

操作は、ドキュメント作成のためにいくつかのオプション要素もサポートしています。

操作の内容を示す短い summary と長い description。description は複数行に対応し、リッチテキスト表現のためにMarkdown（CommonMark）をサポートしています。
tags – リソースまたはその他の修飾子によって操作を論理的にグループ化するために使用されます。タグを使用した操作のグループ化を参照してください。
externalDocs – 追加のドキュメントを含む外部リソースを参照するために使用されます。

操作パラメータ

OpenAPI 3.0 は、パス、クエリ文字列、ヘッダー、およびクッキーを介して渡される操作パラメータをサポートしています。また、POST、PUT、PATCH など、サーバーにデータを送信する操作の要求本文を定義することもできます。詳細については、パラメータの記述と要求本文の記述を参照してください。

パスのクエリ文字列

クエリ文字列パラメータはパスに含めないでください。代わりにクエリパラメータとして定義する必要があります。

不正確

1
paths:
2
  /users?role={role}:

正しい

1
paths:
2
  /users:
3
    get:
4
      parameters:
5
        - in: query
6
          name: role
7
          schema:
8
            type: string
9
            enum: [user, poweruser, admin]
10
          required: true

これは、クエリ文字列のみが異なる複数のパスを持つことができないことも意味します。例：

1
GET /users?firstName=value&lastName=value
2
GET /users?role=value

これは、OpenAPI が一意の操作をパスと HTTP メソッドの組み合わせと見なすためであり、追加のパラメータは操作を一意にしないためです。代わりに、次のような一意のパスを使用する必要があります。

1
GET /users/findByName?firstName=value&lastName=value
2
GET /users/findByRole?role=value

operationId

operationId は、操作を識別するために使用されるオプションの一意の文字列です。提供される場合、これらの ID は API で記述されたすべての操作間で一意である必要があります。

1
/users:
2
  get:
3
    operationId: getUsers
4
    summary: Gets all users
5
    ...
6
  post:
7
    operationId: addUser
8
    summary: Adds a new user
9
    ...
10
/user/{id}:
11
  get:
12
    operationId: getUserById
13
    summary: Gets a user by user ID
14
    ...

operationId の一般的な使用例は次のとおりです。

一部のコードジェネレーターは、この値を使用してコード内の対応するメソッドに名前を付けます。
リンクは、operationId を使用してリンクされた操作を参照できます。

非推奨の操作

特定の操作を deprecated としてマークして、使用を停止する必要があることを示すことができます。

1
/pet/findByTags:
2
  get:
3
    deprecated: true

ツールは、非推奨の操作を特定の方法で処理する場合があります。たとえば、Swagger UI は異なるスタイルで表示します。

Deprecated operation in Swagger UI

グローバルサーバーのオーバーライド

グローバル servers 配列は、パスレベルまたは操作レベルでオーバーライドできます。これは、一部のエンドポイントが API の残りの部分とは異なるサーバーまたはベースパスを使用する場合に役立ちます。一般的な例は次のとおりです。

ファイルアップロードおよびダウンロード操作のベース URL が異なる。
非推奨だがまだ機能しているエンドポイント。

servers
- url: https://api.example.com/v1

1
paths:
2
  /files:
3
    description: File upload and download operations
4
    servers:
5
      - url: https://files.example.com
6
        description: Override base path for all operations with the /files path
7
    ...
8

9
/ping:
10
    get:
11
      servers:
12
        - url: https://echo.example.com
13
          description: Override base path for the GET /ping operation

お探しのものが見つかりませんでしたか？コミュニティに尋ねる間違いを見つけましたか？お知らせください