OAS:OpenAPI Editor/Parameters

From Remain Software

Parameters

This section describes parameters defined for a path an operation or global. A unique parameter is defined by a combination of a name and location.

  • Path parameters are defined under a path and inherited by all operations under that path.
  • Operation parameters are defined under an operation
  • Global parameters are defined under parameters in the global components section and are referenced elsewhere via $ref.

Example of a global parameter in the source view:


Open api global param in source.png


UI-wise, global parameters are always shown when the parameters tab is active:


Open api editor common parameters.png


Add global parameter

To add a global parameter select the bottom tab Paths, then Global Parameters tab then click the (+) button from the local toolbar at the top right.


Open api editor add parameter global.png


A new parameter is added. Give it a name, then following your needs, either add a schema or content. You can delete it using the Delete parameter link from the local top-right toolbar


Open api editor add parameter global new.png


Add schema to global parameter

(If a content type is already used with this parameter, then first delete it by clicking the link Delete content from the local top-right toolbar.)

To add a schema to the parameter, click the red link Add schema... as shown above. You'll be prompted with a wizard to either pick an existing schema or create a new one.

You can change the schema or delete it (will be removed only from the parameter) by using the links Change schema and Delete schema from the local top-right toolbar.

Add content type to global parameter

(If a schema is already used with this parameter, then first delete it by clicking the link Delete schema from the local top-right toolbar.).

To add a content type to the parameter, click the red link Add content... as shown above. Then add a schema to this content.


Open api editor add global parameter schema.png

Add Path Parameter

Please note that parameters added to a path are automatically inherited by all operations under that path.

To add a parameter to the path, select the path you want to add a parameter to. Select the tab having the name of the path on the right side (right to Global Parameters tab). Then click the + button from the top right toolbar (or select New Parameter from drop-down sub-menu).


Open api editor new path paramter.png


A new parameter is added and its input UI shows up. Fill in a name, pick a schema or content type, and edit the rest of the input fields, if needed.


Open api editor new path paramter input.png

Add Operation Parameter

To add a parameter to an operation, select the operation you want to add a parameter to. Select the tab having the name of the operation on the right side (right to Global Parameters tab). Then click the + button from the top right toolbar (or select New Parameter from drop-down sub-menu).


Open api editor add non common parameter.png


A new parameter is added and its input UI shows up. Fill in a name, pick a schema or content type, and edit the rest of the input fields, if needed.


Open api editor new parameter input.png

Delete Parameter

To delete a parameter, click the Delete parameter link from the local menu of the parameter you want to delete.


Open api editor delete parameter button.png

Change Parameter Schema

You can edit a parameter schema by clicking the Change schema link from the local menu of the parameter.


Open api editor edit parameter.png

Delete Parameter Schema

You can delete a parameter schema by clicking the Delete schema link from the local menu of the parameter.


Open api delete parameter schema.png

Delete Parameter Content Type

To delete a parameter content type, click the Delete content link from the local menu of the parameter you want to delete.


Open api editor delete parameter content button.png

Swap Parameter Schema With Content Type

You're using a schema for a parameter and you want to use a content type instead. To do so, first, delete the schema from the parameter by clicking the link Delete schema from the local top-right toolbar.


Open api delete parameter schema.png


Then click the link Add content.


Open api add parameter content.png

Swap Parameter Content Type With Schema

You're using content for a parameter and you want to use a schema instead. To do so, first, delete the content from the parameter by clicking the link Delete content from the local top-right toolbar.


Open api delete parameter content.png


Then click the link Add schema.


Open api add parameter schema button.png