Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
baywet opened this issue Jan 7, 2022 · 0 comments · Fixed by #173
Closed
Assignees
Labels
type:enhancement Enhancement request targeting an existing experience.
Milestone

Comments

@baywet
Copy link
Member

baywet commented Jan 7, 2022

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)

@baywet baywet added the type:enhancement Enhancement request targeting an existing experience. label Jan 7, 2022
@baywet baywet added this to the 1.1 milestone Jan 7, 2022
@baywet baywet modified the milestones: 1.1, 1.0.10 Feb 7, 2022
@irvinesunday irvinesunday removed their assignment Feb 9, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type:enhancement Enhancement request targeting an existing experience.
Projects
None yet
3 participants