パスとオペレーション

OAS 2 このページは、OpenAPI仕様バージョン2（旧Swagger）に適用されます。最新バージョンについては、OpenAPI 3ページをご覧ください。

パスとオペレーション

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

パス

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

paths:
  /ping:
    ...
  /users:
    ...
  /users/{id}:
    ...

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

パス・テンプレート

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

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

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

オペレーション

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

paths:
  /ping:
    get:
      responses:
        200:
          description: OK

パラメータとレスポンススキーマを含む、より詳細な例

paths:
  /users/{id}:
    get:
      summary: Gets a user by ID.
      description: >
        A detailed description of the operation.
        GitHub Flavored Markdown can be used for rich text representation,
        such as **bold**, *italic* and [links](https://swagger.dokyumento.jp).
      operationId: getUsers
      tags:
        - users
      produces:
        - application/json
        - application/xml
      parameters:
        - name: id
          in: path
          description: User ID
          type: integer
          required: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/User'
      externalDocs:
        url: http://api.example.com/docs/user-operations/
        description: Learn more about User operations provided by this API.
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
    required:
      - id
      - name

オペレーションは、ドキュメントを目的としたオプションの要素をいくつかサポートしています。

オペレーションの動作内容を説明する短い`summary`と長い`description`です。`description`は複数行にすることができ、リッチテキスト表現のためにGitHub Flavored Markdownをサポートしています。
`tags`は、Swagger UIでオペレーションをグループ化するために使用されます。
`externalDocs`を使用すると、追加のドキュメントを含む外部リソースを参照できます。

オペレーション・パラメータ

Swaggerは、パス、クエリ文字列、ヘッダー、リクエスト本文を介して渡されるオペレーション・パラメータをサポートしています。詳細については、パラメータの説明を参照してください。

operationId

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

  /users:
     get:
       operationId: getUsers
       summary: Gets all users.
       ...
     post:
       operationId: addUser
       summary: Adds a new user.
       ...
   /user/{id}:
     get:
       operationId: getUserById
       summary: Gets a user by user ID.
       ...

パス内のクエリ文字列

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

paths:
  /users?role={role}:

正しい例

paths:
  /users:
    get:
      parameters:
        - in: query
          name: role
          type: string
          enum: [user, poweruser, admin]
          required: false

これはまた、以下のように、クエリ文字列のみが異なる複数のパスを持つことができないことを意味します。

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

これは、Swaggerが一意のオペレーションをパスとHTTPメソッドの組み合わせと見なし、追加のパラメータはオペレーションを一意にしないためです。代わりに、以下のように一意のパスを使用する必要があります。

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

非推奨としてマークする

特定のオペレーションを`deprecated`としてマークして、使用を中止する必要があることを示すことができます。

  /pet/findByTags:
    get:
      deprecated: true

ツールは、非推奨のオペレーションを特定の方法で処理する場合があります。たとえば、Swagger UIはそれらを異なるスタイルで表示します。

Deprecated operation in Swagger UI

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