Interactive documentation support helps users to understand and experience the APIs better. WSO2 API Manager provides this functionality through the integration of Swagger (https://developers.helloreverb.com/swagger). Swagger is a specification and a complete framework implementation for describing, producing, consuming, and visualizing RESTful Web services. You can load APIs that are described in simple, static JSON representation through the Swagger UI and and make them available as interactive documentation.

The idea of this interactive console is allowing users to test the APIs and get to know how they respond without subscribing to the APIs. When an API is created in API Publisher, the JSON representation of that API is automatically generated and saved into the registry as an API definition. This API definition describes the API using the information provided at the time it is created. You can modify the API definition using the Doc tab in the management console. In API Store, the Swagger UI discovers the API definition for each API and displays the interactive documentation in the API's Documentation tab.

The sections below explain how to create an interactive documentation for an API:

Enabling cross-origin resource sharing

Swagger-based interactive documentation allows you to try out APIs from the documentation itself. It is a Java Script client that runs in the API Store and makes Java Script calls from the Store to the API Gateway. Since the API Store and Gateway run on two different ports, you must enable cross-origin resource sharing (CROS) between the two using CORS configuration in <APIM_HOME>/repository/conf/api-manager.xml file. Given below is a sample configuration of CROS and a description of its XML elements:

Specify None as the Auth Type of OPTIONS

For each of the resource that has HTTP verbs requiring Authentication (i.e., Auth Type is not NONE), enable OPTIONS with None Auth type. For example, as the following screen shot shows, resources with /* URL Pattern has HTTP verbs with Auth Type as Application & Application User. Therefore, we must give None as the Auth Type of OPTIONS. This is to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway. But, if no authentication is needed for any of the HTTP verbs, you don't have to specify None Auth type to OPTIONS.

The example below shows how we have changed the path for all the HTTP methods of the API definition from /phoneverify/1.0.0/ to /phoneverify/1.0.0/CheckPhoneNumber using both the text editor and graphical tree editor:

Invoking the interactive documentation

Generate access tokens. You need them to invoke the API in the next steps.

Select the API again and go to the API Console tab, which shows the interactive documentation of the API.

Provide the necessary parameters and click Try it out to call the API. For example, the PhoneVerification API takes two parameters: the phone number and a license key, which is set to 0 for testing purposes.

Give the API payload as PhoneNumber=18006785432&LicenseKey=0 where /phoneverify is the context and 1.1.0 is the version. The rest of the URL is driven by the backend service requirements.

Authorization

In the authorization header, pass the application key that was generated at the time a user subscribes to an API. This is prefixed by the string "Bearer". For example, Bearer q6- JeSXxZDDzBnccK3ZZGf5_AZTk.

WSO2 API Manager enforces OAuth security on all the published APIs. Consumers who talk to the API Manager should send their credentials (application key) as per the OAuth bearer token profile. If you don't send an application key or send a wrong key, you will receive a 401 Unauthorized response in return.

Note the response for the API invocation that appears as follows:

Within a minute after the first API invocation, make another attempt to invoke the API and note that the second invocation results in a throttling error.

This is because you applied a Bronze tier at the time you subscribed to the API and the Bronze tier only allows one API call per minute.