Skip to content

Making representations a first class concept to address a number of structural concerns #721

@darrelmiller

Description

@darrelmiller

This is a proposal to address a number of the issues aggregated under #560.
Specifically:

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: csv

The 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:pets

The 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.

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions