OAS:OpenAPI Editor/Servers

From Remain Software

Servers

In OpenAPI 3.0, you use the servers array to specify one or more base URLs for your API. All API endpoints are relative to the base URL.


Openapi servers tab.png


Add Server

To add a server, either select the + button from the local toolbar or right-click the Servers node then select New Server from the popup menu.


Openapi add server.png


Fill in the server URL and the description then hit Finish. The newly created server is added to servers on the left view and its content appears on the right editor.


Openapi new server wizard.png

Edit Server

To edit a server, right-click the server you want to edit then select Edit from the popup menu.


Openapi edit server.png

Add Server Variable

To add a server variable, right-click the server you want to add a variable to, then select New Variable from the popup menu.


Openapi add sever variable.png


Fill in the server variable name and the default value then hit Finish.


Openapi new server variable wizard.png


The newly created server variable appears on the left and its content on the right editor.


Openapi new server variable editor.png

Edit Server Variable

You can edit a server variable by right-clicking it then selecting Edit from the popup menu.


Openapi edit server variable.png

Overriding Servers

The global servers array can be overridden on the path level or operation level. This is handy if some endpoints use a different server or base path than the rest of the API.


To override a global server, select path or operation node, and in the appropriate servers tab click on the + button or Override global servers link, then the wizard with global servers will be displayed, select a server and hit Finish.


Openapi add-global servers.png


Delete Global Server

To delete a server, select the server to be deleted and click on the X button from the local toolbar or right-click the server node then select delete from the popup menu.


Openapi delete overrided golbal server.png

Mock Server

Our mock server is fully integrated, automated, and locally running within our studio. You don't have to configure anything.

It automatically validates the incoming payload following your OpenAPI definitions.

How it works

It automatically reads and keeps track of the OpenAPI model document you're working on. By doing so:

  • It automatically validates and handles the incoming payload for:
    • Paths
    • Request bodies
    • Parameters
    • Responses
  • It automatically builds needed data and calls back registered endpoints (callbacks), if any, as defined in your OpenAPI document.

Then generates a mock response based on the definitions in your OpenAPI document. if a schema provides an example, it's used in the response payload. Otherwise, a fairly realistic example is generated.

If a payload (or portion thereof) is invalid, an explanatory error response is sent back.

How to use it

To use this mock server in the web view, select the URL containing the path "/mockserver/" from the Servers dropdown. This mock-server URL can also be called/used elsewhere. E.g., Remain API Test, command line, or from within code.

Note: Most changes you're doing in your OpenAPI document are picked automatically by the mock-server, if you don't see your changes in the response payload, then just refresh your browser.


Openapi mock server.png


To run a test of all operations under a path against the mock server, right-click the path you want to test, select the Run menu, then from the servers dropdown, select the URL containing the path "/mockserver/" then click OK.


Openapi mock server run path.png

Circumvent CORS restriction when testing

If the server you're using doesn't (yet) support CORS requests, then we got you covered. You may want to use the local CORS-ed tunneling server which you recognize with the /CORS/ subpath in the server URL. For each server you define in the Servers tab, we automatically add a CORS-ed one in the servers drop-down in the Web View. (The added CORS-ed servers will not be added to your OpenAPI document)


Openapi editor cors.png