OAS:OpenAPI Editor/Examples

From Remain Software

Examples

You can add examples to parameters, properties, and objects to make the OpenAPI specification of your web service clearer. Examples can be read by tools and libraries that process your API in some way. For example, an API mocking tool can use sample values to generate mock requests. You can specify examples for objects, individual properties, and operation parameters.


Add Global Example

To add a global example, select the Examples tab, then the + button in the top-right of the editor.


Openapi examples global add.png

Refer To Global Example

You can create a global example and refer to it to avoid repetition. To refer to a global example click the Refer to global example link in the Examples tab.

Or select the Refer To Global Example from the toolbar menu.


Openapi examples refer to global 1.png

Delete Global Example

To delete a global example, select the Examples tab, then click Delete example link within the example you want to delete.


Openapi exmaples delete global.png

Update Global Example

A global example can be updated by directly changing the content of any of its input fields.


Openapi exmaples update global.png

Edit Schema Example

Right-click the schema you want to edit its example or add a new one to. Then select the Edit Example menu.


Openapi examples generate schema example.png


You'll be redirected to the Examples tab. There you can click the Add new example link. Alternatively, you can also use the menu New Example from the top toolbar.


Openapi examples schema new example.png

Generate Schema Example

Instead of writing a schema example from scratch, you can generate one and edit it to your needs.

To Generate a schema example, right-click the schema then select the Edit Example menu.


Openapi examples generate schema example.png


You'll be redirected to the Examples tab. There you can click the Generate example link.


Openapi examples generate schema example2.png


You can always re-generate a new schema example by clicking the Generate example menu.


Openapi examples generate schema example3.png

Edit Inline Schema Example

An inline schema is a schema that is not defined in the components section of your OpenAPI document. You see inline schemas usage mostly within parameters, request bodies or responses.

You can edit an inline schema example in two ways:

1- In the Attributes tab (under the Attributes & Properties view). This is handy for non-object schemas where the example itself shouldn't be large or complex such as a number or short string. In this case, click the inline schema link to activate the Attributes tab. There in the Example input field, fill in your example.


Openapi examples inline schema 1.png


2- Otherwise, click the Show example just beside the schema. You'll be redirected to the Examples tab where you have more room to edit your schema example. This is handy for a full JSON example. There you can edit your current example, add a new one, refer to a global one, or just generate one automatically.


Openapi examples main tab.png

Edit Parameter Examples

To edit a parameter examples, click the Edit Examples link from the local toolbar of the parameter you want to edit. You'll be redirected to the Examples tab where you can edit this parameter examples.


Openapi examples parameter.png

Edit Request Body Examples

Click the Edit examples link within the request body content.


Openapi examples request body.png


You'll be redirected to the Examples tab. There you can click the Add new example link. Alternatively, you can also use the menu New Example from the top toolbar.


Openapi examples schema new example.png

Edit Response Examples

Click the Edit examples link within the response content.


Openapi examples response.png


You'll be redirected to the Examples tab. There you can click the Add new example link.

Alternatively, you can also use the menu New Example from the top toolbar.


Openapi examples schema new example.png