-
Notifications
You must be signed in to change notification settings - Fork 9.2k
Description
This is a proposal to address a number of the issues aggregated under #560.
Specifically:
- Having multiple schemas for requests and responses Allow for multiple response schemas for each response code #270
- It removes the produces/consumes ambiguity described here Clarify when consumes/produces take effect #581
- It extends on @jasonh-n-austin 's addition of the RequestBody object Request bodies moved out of parameters #670
- It avoids some of the issues around formData by making it obsolete Allow different Content Types in File type parameters #222
The basic premise is that OpenAPI models operations that interact with resources using a specific HTTP method. The interaction involves sending representations and retrieving those representations. A single operation may support different representations identified by a media-type.
Consider the following GET operation that returns one of two representations.
get:
description: Returns pets based on ID
summary: Find pets by ID
operationId: getPetsById
responses:
'200':
description: pet response
representations:
application/json:
schema:
type: array
items:
$ref: '#/definitions/Pet'
text/html:
default:
description: error payload
representations:
application/json:
schema:
$ref: '#/definitions/ErrorModel'
text/html:
parameters:
- name: id
in: path
description: ID of pet to use
required: true
type: array
items:
type: string
collectionFormat: csvThe description and headers properties of a response object stay, but the schema and examples move under the representation object that is defined as a property of the representations object. The examples property will need to change to either an array of objects, or a single object because all examples would be for the same media type.
By defining the supported media types on the representations object, there is no longer a need for a produces array.
It is important to note that different representations should not be semantically different when accompanied with the same class of status code. A request to a resource should always the same thing (for some unfortunately nebulous definition of thing). However, the syntax of that representation may be different and the amount of information contained may be different, but from a consumer's perspective. it is same concept, regardless of the representation. This is why the description property is the same for all representations.
The following is an example of a POST request that may send a HTML form as a request body.
tags:
- pet
summary: Updates a pet in the store with form data
description: ""
operationId: updatePetWithForm
parameters:
- name: petId
in: path
description: ID of pet that needs to be updated
required: true
type: string
requestbody:
description: Updated status of the pet
required: false
representations:
application/x-www-form-urlencoded:
schema:
properties:
name:
description: Updated name of the pet
type: string
status:
description: Updated status of the pet
type: string
required:
- status
responses:
'200':
description: Pet updated.
representations:
application/json:
application/xml:
'405':
description: Invalid input
representations:
application/json:
application/xml:
security:
- petstore_auth:
- write:pets
- read:petsThe structure of the HTML form that is passed as a body are no longer intermixed with the URI parameters and are described by a schema object in the representation object. This enables us to support all the different form related media types. There would no longer be any need for the formData parameter type and no need for the consumes array.
One open question is whether there is a value to allowing representation objects (media type, schema and examples) to be defined within the reusable components section.