Repository navigation
Actions/Functions request body/response schemas are duplicated #241
Description
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: actionHere 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.
Activity
nikithauc commentedon Jun 27, 2022
microsoft/OpenAPI.NET#913 (comment)
baywet commentedon Aug 17, 2022
Continuing on the comment left by Irvine Sunday (@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
/meand 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
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 commentedon Aug 19, 2022
Vincent Biret (@baywet) Yes, thanks for the additional info.