OAS 3 support

This release adds OAS 3 support to API Console.
The changes are backward compatible. This means that this release only adds functionality to the existing API console without changing or removing existing. The exception is the authorization data attached to the request object but because API Console handles request internally and applies auth data to request object this is not a breaking change. If you read the auth property of the request object then your application may break as now it returns an array to support multi authorization in OAS.

Support for multi-server definitions

This brings a number of changes to how the console processes base URI and server definition:

• Server is selected automatically to the first server on the list, unless selection is already made.
  The server selector attributes are:
  • baseUri (string): overrides any server definition value
  • allowCustomBaseUri (boolean): When true a custom URI can be provided by the user
  • servers (array): Array of servers to be rendered
  • serverType (string): Currently selected base URI type. (‘server’ when provided in the amf model, ‘uri’ if provided through the custom-base-uri slot and custom if custom URI option is selected)
  • serverValue (string): Current value of the server selector
• The server selector is rendered:
  • By default in the request editor in full view
  • In the documentation view when the console is rendered in the narrow view and the current view is the documentation
  • In both cases the selector is not rendered when there is less than 2 options to render
• The api-summary screen now renders a list of base URIs from each server definition. It renders a single base URI (as before) if there’s only one server.

Custom servers

In addition to the server selector now developers can insert a list items as child nodes of the console that will be rendered in the selector. In this case the selector is always rendered.

To the server selector with custom items in it add anypoint-items (or other list items) as children to api-server-selector, api-console, api-documentation or api-request-panel components.

Each anypoint-item must:

• Have the “slot” attribute set to “custom-base-uri”
• Have the “value” attribute with the base URI value to add

Example:

<api console>
  <anypoint-item slot=”custom-base-uri” value=”https://base1.com”>Base 1</anypoint-item>
  <anypoint-item slot=”custom-base-uri” value=”https://base2.com”>Base 2</anypoint-item>
</api-console>

New authorization methods

The authorization panel for the request editor was redesigned and rebuilt from scratch to enable OAS’ multi-authorization feature. An OAS API can define a number of authorization definitions that can be applied to the request. This changes the way how the console handles the authorization data provided by the user.

Comparing to the previous version:

• Authorization data are applied to the request in the moment when the user decide to send the request and not when the data in the editor change
• The “auth” property of the request object is now an array of all security definitions applied to the request
• When the authorization settings only manipulate headers or query parameters then this parameters are applied to the request object at the moment of dispatching the “api-request” event
• Settings for each authorization depends on the type of the security scheme. Learn more in the api-authorization component documentation https://github.com/advanced-rest-client/api-authorization#authorization-settings

OAS’ links and callbacks

API Console now renders links and callback documentation in the method (operation) documentation screen. This is not supported by the request editor at the time as there’s no actual flow in making a request.

Other changes

• Added support for “no-auto-encoding” annotation. If enabled on an URI parameter, the API Console will not automatically encode the URI parameter value from the specification. For example:

paramName:
  (no-auto-encoding):
    type: string

Deprecation notice

The URL editor is planned to be removed from the request editor. The reason is to simplify the UI and request editing logic. The end-user now can use the server selector to provide the base URI if needed and the rest of URI/query parameters can be defined in the request editor.
Currently we are preparing to gather usage data from the URL editor in the Anypoint platform to recognize possible result of this change. The removal is planned in Q4 2020.