Actions/Functions request body/response schemas are duplicated

[baywet]

Any OData action/function can be bound to multiple "places" resulting in multiple path items being described. The issue is the request body schema for actions and the response for actions and functions being described inline instead of being declared as components and reused. This results in duplication for each instance, which degrades the SDKs experience (size, auto-completion etc...) Semantically, those instances are identical, any annotation applied to the function/action will apply across all instances.

/me/microsoft.graph.sendMail:
    description: Provides operations to call the sendMail method.
    post:
      tags:
        - me.Actions
      summary: Invoke action sendMail
      operationId: me.sendMail
      requestBody:
        description: Action parameters
        content:
          application/json:
            schema:
              type: object
              properties:
                Message:
                  $ref: '#/components/schemas/microsoft.graph.message'
                SaveToSentItems:
                  type: boolean
                  default: false
                  nullable: true
        required: true
      responses:
        '204':
          description: Success
        4XX:
          $ref: '#/components/responses/error'
        5XX:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: action
  /me/microsoft.graph.translateExchangeIds:
    description: Provides operations to call the translateExchangeIds method.
    post:
      tags:
        - me.Actions
      summary: Invoke action translateExchangeIds
      operationId: me.translateExchangeIds
      requestBody:
        description: Action parameters
        content:
          application/json:
            schema:
              type: object
              properties:
                InputIds:
                  type: array
                  items:
                    type: string
                TargetIdType:
                  anyOf:
                    - $ref: '#/components/schemas/microsoft.graph.exchangeIdFormat'
                SourceIdType:
                  anyOf:
                    - $ref: '#/components/schemas/microsoft.graph.exchangeIdFormat'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: Collection of user
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/microsoft.graph.convertIdResult'
        4XX:
          $ref: '#/components/responses/error'
        5XX:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: action

Here I'd expect the sendMail request body to be declared as a component (sendMailRequestBody or similar) so it can be re-used in other instances (/users/id/microsoft.graph.sendMail), same for the translateExchangeIds. I'd also expect the translateExchangeIds response schema to be declared as a component to be reused.

[nikithauc]

https://github.com/microsoft/OpenAPI.NET/issues/913#issuecomment-1164422147

[baywet]

Continuing on the comment left by @irvinesunday on the other thread reported by Nikitha here. I'm not suggesting we have a single type across different actions/functions. My argument is that for a single action/function that is bound different places (e.g. sendMail that is bound to /me and to /users/{id}) both the request body and the response should be component schemas instead of being defined inline multiple times.

Instead of having what's present in my original message we should have a component schema microsoft.graph.sendMailRequestBody with this content

              type: object
              properties:
                Message:
                  $ref: '#/components/schemas/microsoft.graph.message'
                SaveToSentItems:
                  type: boolean
                  default: false
                  nullable: true

And the operation request body content should ref to it.

If we have different actions/functions I'm not expecting them to share a referenced schema. E.g. if we have one function returning a collection of applications an another returning a collection of users, I'm expecting them to have two different response schemas. But if the latter is reused a couple of different places, I'm expecting those different instances to re-use the same component schema.

I hope this makes the intent clearer?

[millicentachieng]

@baywet Yes, thanks for the additional info.