パスと操作

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

パス

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

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

すべてのパスは basePath に相対的です (API ホストとベース URL を参照)。完全なリクエスト URL は scheme://host/basePath/path として構築されます。

パスのテンプレート化

Swagger はパスのテンプレート化をサポートしており、波括弧 {} を使用して URL の一部をパスパラメーターとしてマークできます。

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

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

操作

各パスには、そのパスにアクセスするために使用できる操作 (HTTP メソッド) を定義します。Swagger 2.0 は get, post, put, patch, delete, head, options をサポートしています。1 つのパスで複数の操作をサポートできます。たとえば、ユーザーのリストを取得するための GET /users と、新しいユーザーを追加するための POST /users などです。Swagger は、パスと 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
      summary: Gets a user by ID.
5
      description: >
6
        A detailed description of the operation.
7
        GitHub Flavored Markdown can be used for rich text representation,
8
        such as **bold**, *italic* and [links](https://swagger.dokyumento.jp).
9
      operationId: getUsers
10
      tags:
11
        - users
12
      produces:
13
        - application/json
14
        - application/xml
15
      parameters:
16
        - name: id
17
          in: path
18
          description: User ID
19
          type: integer
20
          required: true
21
      responses:
22
        200:
23
          description: OK
24
          schema:
25
            $ref: "#/definitions/User"
26
      externalDocs:
27
        url: http://api.example.com/docs/user-operations/
28
        description: Learn more about User operations provided by this API.
29
definitions:
30
  User:
31
    type: object
32
    properties:
33
      id:
34
        type: integer
35
      name:
36
        type: string
37
    required:
38
      - id
39
      - name

操作は、ドキュメント作成の目的でいくつかのオプション要素をサポートしています

操作が何を行うかの短いsummaryとより長いdescription。descriptionは複数行に対応し、リッチテキスト表現のためにGitHub Flavored Markdownをサポートしています。
tagsはSwagger UIで操作をグループ化するために使用されます。
externalDocsは、追加のドキュメントを含む外部リソースを参照することを可能にします。

操作パラメーター

Swagger は、パス、クエリ文字列、ヘッダー、リクエストボディを介して渡される操作パラメーターをサポートしています。詳細については、パラメーターの記述を参照してください。

operationId

各操作には、一意の operationId を指定できます。一部のコードジェネレーターでは、この値を使用してコード内の対応するメソッドに名前を付けます。

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
      ...

パス内のクエリ文字列

クエリ文字列パラメーターはパスに含め**てはなりません**。代わりにクエリパラメーターとして定義する必要があります。不正な例

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

正しい例

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

これは、クエリ文字列のみが異なる複数のパスを持つことが不可能であることを意味します。

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

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

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

非推奨としてマーク

特定の操作をdeprecatedとしてマークして、使用を停止するよう指示できます。

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

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

Deprecated operation in Swagger UI

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