OpenAPIのパスパラメータとクエリパラメータ

OpenAPIのパラメータ

パラメータはエンドポイントの動作を変更する入力です。OpenAPI 3.0は4つのパラメータ位置をサポートします：path、query、header、cookie。それぞれ定義と使用に固有のルールがあります。

パスパラメータ

パスパラメータはURLの一部であり常に必須です：

/users/{userId}/posts/{postId}:
  get:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: postId
        in: path
        required: true
        schema:
          type: integer

パスパラメータは required: true でなければなりません — URL構造に埋め込まれているため常に必須です。

クエリパラメータ

クエリパラメータはレスポンスをフィルタ、ソート、変更します：

/products:
  get:
    parameters:
      - name: category
        in: query
        schema:
          type: string
          enum: [electronics, clothing, books]
      - name: sort
        in: query
        schema:
          type: string
          enum: [price_asc, price_desc, newest]
          default: newest

再利用可能なパラメータ

一度定義して、どこでも参照：

components:
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1

paths:
  /users:
    get:
      parameters:
        - $ref: "#/components/parameters/PageParam"