OAS:OpenAPI Editor/Responses

From Remain Software

Responses

An OpenAPI document needs to specify responses for all API operations. Each operation must have at least one response indicating successful handling of the request by the server. A response is defined by its HTTP status code and the data returned in the response body and/or headers


Open api editor response tab.png


Add new Response

To add a new response either click the + button or New Response from the drop-down menu from the local toolbar.


Open api editor response tab menu.png


A new response is added with a default content type. Input fields are being shown for edition. Local link buttons are also shown when hovering over this new response.


Open api editor new response.png

Delete a Response

To delete a response, select the response tab then click the delete button (the red X) from the local toolbar.


Open api editor delete response menu.png

Update Response

Use the response fields to update it. Hover over of the response to view other link buttons to change the response schema, delete the response content or edit the content schema example.


Open api editor edit response fields.png

Add New Response Content Type

Select New Response Content Type from the local toolbar.


Openapi editor response content type menu.png.png


Update/Delete Response Content Type

A response may contain multiple content types. To delete a content type from a response, hover over it then click the link Delete content from that content local menu.


Open api editor esponse edit.png

Update Response Content Type Schema

You can add a schema to the content type by clicking the red link "Add schema" at the bottom of the content type. Or click Change schema link from the local toolbar.


Open api editor new response content schema.png


You can either select an existing schema:


Open api editor new requestbody content schema new wz.png


Or create a new schema on the fly and use it in this content type. You can create an inline schema by letting the name field blank.

If you give the schema being created a name, it'll be also automatically added to the global components/schemas. It's then not an inline schema but referred to, by the content type.


Open api editor new requestbody content schema new wz2.png

Response Headers

Responses from an API can include custom headers to provide additional information on the result of an API call. For example, a rate-limited API may provide the rate limit status via response headers as follows:


Openapi editor response header intro.png


Add Response Header

To add a new header, select a response then select New Header from the menu at the top right. A new header UI is shown. Give it in a name and eventually fill in other fields. Then give it a schema or content. To select a schema click the link Add schema... at the bottom of the header UI. You'll be prompted with a wizard to select an existing schema or create a new one. To use a content type with this header, click the link Add content... at the bottom of this header UI.


Openapi editor response header add.png


Delete Response Header

To delete a response header, click the Delete header link from that header local toolbar.


Openapi editor response header delete.png