5/18/2020 PRINT:OAS:Remain API Studio - Remain Software PRINT:OAS:Remain API Studio From Remain Software Welcome to the index of the Remain API Studio. OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API. This editor helps you easily create and edit your OpenAPI file. Contents 1 Import OpenAPI 2 Export OpenAPI 3 Schemas 3.1 Add New Schema 3.2 Update Schema 3.2.1 Update Schema Name/Description 3.2.2 Update Schema Properties/Attributes 3.3 Delete Schema 3.4 Import Schema 3.5 Extract Schema From JSON Sample/Payload 3.6 Composite Schema 3.6.1 Add Sub-Schema 3.6.2 Change Sub-Schema (composite) Keyword 3.7 Schema Properties 3.8 Additional Properties 4 Paths 4.1 Add Path 4.2 Edit Path 4.3 Delete Path 4.4 Duplicate Path 4.5 Copy|Cut Operation 4.6 Parameters 4.7 Add global parameter 4.8 Add a path/operation parameter 4.9 Edit/Delete parameter 5 Operations 5.1 Add Operation 5.2 Update Operation 5.3 Delete Operation 6 Request Bodies 6.1 Add A Global Request Body 6.2 Add An Operation Request Body 6.3 Add Request Body Content Type 6.4 Delete Request Body Content Type 6.5 Add Schema to Request Body Content Type 6.6 Update Schema to Request Body Content Type 6.7 Delete Request Body 6.8 Update Request Body 7 Responses 7.1 Add new Response 7.2 Delete a Response 7.3 Update Response 7.4 Add new Response Content Type 7.5 Update/Delete Response Content Type 7.6 Update Response Content Type Schema 8 Tags 8.1 Add Global Tag 8.2 Add Operation Tag 8.3 Update Tag 8.4 Delete Tag 8.4.1 Delete Global Tag 8.4.2 Delete Operation Tag 9 Extensions 9.1 Add Extension 9.2 Edit/Delete Extension 10 Authentication and Authorization 10.1 Add Security Scheme 10.2 Delete Security Scheme 10.3 Update Security Scheme 10.4 Add OAuth Flow 10.5 Update OAuth Flow 10.6 Delete OAuth Flow 10.7 Define Global Security 10.8 No Global Security Usage 10.9 Define Operation Security 10.10 Inherit Global Security 10.11 No Security On Operation Level 11 Servers https://remainsoftware.com/wiki/index.php?title=PRINT:OAS:Remain API 1/43 Studio&printable=yes 5/18/2020 PRINT:OAS:Remain API Studio - Remain Software 11.1 Add Server 11.2 Edit Server 11.3 Add Server Variable 11.4 Edit Server Variable 11.5 Overriding Servers 11.5.1 Delete Global Server 11.6 Overview 11.7 Generate Client 11.8 Generate Server 12 Links 12.1 Add Global Link 12.2 Delete Global Link 12.3 Update Global Link 12.4 Add Parameter To Link 12.5 Delete Parameter From Link 12.6 Add Link To Response 12.7 Add Link Reference To Response 13 Examples 13.1 Add Global Example 13.2 Delete Global Example 13.3 Update Global Example Import OpenAPI To import an OpenApi file into the editor, click the drop-down menu (top right). You can import a file from a Local file-system. To do so, select Import Local OpenAPI from the drop-down menu then pick a file from the files dialog you're prompted with. Or Remote location. To do so, select Import Remote OpenAPI from the drop-down menu, fill in the location URL in the location field, then hit Enter or the Read button. The components of the selected OpenApi file will be shown (e.g., the image below). Select the option that suits you then hit Finish button. You are able to import all or parts of the specification. https://remainsoftware.com/wiki/index.php?title=PRINT:OAS:Remain API Studio&printable=yes 2/43 5/18/2020 PRINT:OAS:Remain API Studio - Remain Software Export OpenAPI To export the currently opened file in the editor, click the export button beside the import button described below, in the local toolbar. By default, you can only export to the local file-system but other systems (like TD/OMS) may extend this functionality. (https://remainsoftware.com/wiki/index.php/Special:MyLanguage/OAS:O penAPI_Editor) Schemas The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. The schema view (tab) allows you to handle the schemas that reside in the components part of your OpenAPI file. To manage your OpenAPI schemas, select the Schemas tab at the bottom of the editor: https://remainsoftware.com/wiki/index.php?title=PRINT:OAS:Remain API Studio&printable=yes 3/43 5/18/2020 PRINT:OAS:Remain API Studio - Remain Software Add New Schema You can add a new schema either by clicking the + (plus) button from the toolbar: or right-clicking the node named Schemas in the view, then selecting New Schema from the popup menu: Then a wizard appears. Fill in the schema name, type and optionally the description then click Finish. https://remainsoftware.com/wiki/index.php?title=PRINT:OAS:Remain API 4/43 Studio&printable=yes 5/18/2020 PRINT:OAS:Remain API Studio - Remain Software In that wizard you get also the possibility to specify: Whether the being created schema is an array of schemas by (un)checking the checkbox named Array of Whether it's of primitive type (e.g., string or integer) or refers yet to an existing schema. Pick a type from the drop-down box right to Array of button The type format from the Format dropdown. (enabled automatically when relevant) Update Schema Update Schema Name/Description To edit a schema name or description. Select a schema then either right-click it then select Edit from the popup menu. Or just click the edit icon from the local toolbar. https://remainsoftware.com/wiki/index.php?title=PRINT:OAS:Remain API Studio&printable=yes 5/43 5/18/2020 PRINT:OAS:Remain API Studio - Remain Software Update Schema Properties/Attributes To do more than a schema's name or/and description edition, please use the views Schema Attributes or/and Components Details. If they're not opened, you can do so using the main toolbar. Choose Windows -> Show View -> Other... then OpenApi. Both views will react on schema selection. Please note that a schema property (as shown in the middle view above) is in its turn a schema. So you can select a property and update it using Schema Attributes or/and Components Details as well. Delete Schema To delete a schema. select the schema to delete then either right-click it then select Delete from the popup menu. Or just click the delete icon from the local toolbar. Import Schema https://remainsoftware.com/wiki/index.php?title=PRINT:OAS:Remain API 6/43 Studio&printable=yes 5/18/2020 PRINT:OAS:Remain API Studio - Remain Software You can import schema into your openApi file by clicking the import (dorp-down) button from the local toolbar. Schemas can be imported either from the local file-system or remotely by using a URL: To import schemas from the local file-system select Import Local Schema, then pick the schemas file from the file dialog you're prompted with. To import remote schemas, fill in the schemas location (e.g., http://example.com/api/some-api.json) then click the Read button or hit enter. Then select the schemas you want to import then hit Finish. Extract Schema From JSON Sample/Payload You can extract a schema definition from an existing JSON sample/payload. Click the Import icon in the local Schemas toolbar or right-click any schema then select Import From Schema Payload You're then prompted with a wizard, paste your valid JSON sample and fill in a name for the schema to extract. Then click Finish. The newly extracted schema definition is visible in the Schemas view. It's added to the schemas under the components section in your API file. https://remainsoftware.com/wiki/index.php?title=PRINT:OAS:Remain API Studio&printable=yes 7/43 5/18/2020 PRINT:OAS:Remain API Studio - Remain Software Composite Schema Add Sub-Schema The OpenAPI Specification allows combining and extending model definitions, in effect offering model composition. Example of a composite schema. oneOf in this example takes an array of object definitions. A response payload MAY be described to be exactly one and only one of them: ... components: schemas: Pet: ... oneOf: - $ref: '#/components/schemas/Bird' - $ref: '#/components/schemas/Bunny' - $ref: '#/components/schemas/Cat' ... https://remainsoftware.com/wiki/index.php?title=PRINT:OAS:Remain API Studio&printable=yes 8/43 5/18/2020 PRINT:OAS:Remain API Studio - Remain Software To combine schemas using specs' keywords anyOf, allOf, oneOf or not. That is, add a subschema to an existing schema (making it composite), right-click a schema then select Add Sub-Schema from the popup menu. Then fill in the wizard you're prompted with. You don't have to fill in the name if you merely want to add an existing schema as subschema (That is, you picked an existing schema as type from the drop-down box beside the Type label). Please note that if you fill in the name of the subschema you're about to add, then a new schema will always be created, added to the components/schemas section. then added as subschema. This comes handy if you wat to create a new schema then refer it from a composite one in one go.