Skip to content

Path parameters should be declared on the Path Item object and not on the Operation object #159

Closed
@baywet

Description

@baywet

Since the path item object supports declaring parameters, the parameters that are in path should be declared on this object, not the operation object. This way if we have multiple operations on the same path items, the description would not have a duplicate description of the path parameter for each operation.

  '/Airports/{IcaoCode}':
    description: Provides operations to manage the collection of Airport entities.
+   parameters:
+   - name: IcaoCode
+      in: path
+      description: 'key: IcaoCode of Airport'
+      required: true
+      schema:
+        type: string
+      x-ms-docs-key-type: Airport
    get:
      tags:
        - Airports.Airport
      summary: Get entity from Airports by key
      operationId: Airports.Airport.GetAirport
      parameters:
-       - name: IcaoCode
-         in: path
-         description: 'key: IcaoCode of Airport'
-         required: true
-         schema:
-           type: string
-         x-ms-docs-key-type: Airport
        - name: $select
          in: query
          description: Select properties to be returned
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - Name
                - IcaoCode
                - IataCode
                - Location
              type: string
        - name: $expand
          in: query
          description: Expand related entities
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - '*'
              type: string
      responses:
        '200':
          description: Retrieved entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.OData.Service.Sample.TrippinInMemory.Models.Airport'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    patch:
      tags:
        - Airports.Airport
      summary: Update entity in Airports
      operationId: Airports.Airport.UpdateAirport
      parameters:
-       - name: IcaoCode
-         in: path
-         description: 'key: IcaoCode of Airport'
-         required: true
-         schema:
-           type: string
-         x-ms-docs-key-type: Airport
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Microsoft.OData.Service.Sample.TrippinInMemory.Models.Airport'
        required: true
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
        - Airports.Airport
      summary: Delete entity from Airports
      operationId: Airports.Airport.DeleteAirport
      parameters:
-       - name: IcaoCode
-         in: path
-         description: 'key: IcaoCode of Airport'
-         required: true
-         schema:
-           type: string
-         x-ms-docs-key-type: Airport
        - name: If-Match
          in: header
          description: ETag
          schema:
            type: string
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation

Note the logic needs to be updated here

protected virtual void SetParameters(OpenApiOperation operation)

Metadata

Metadata

Assignees

Labels

type:enhancementEnhancement request targeting an existing experience.

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions