Adding Documentation Using Swagger

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, Swagger UI discovers the API definition for each API and displays the interactive documentation under the API's Overview tab.

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

In the examples we discuss here, we use an API named FindFeeds, which is based on the online search functionality provided by YouTube (http://www.youtube.com). We use http://gdata.youtube.com/feeds/api/standardfeeds as the Production Url/Endpoint.

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 (CORS) between the two using CORS configuration in <APIM_HOME>/repository/conf/api-manager.xml file. Given below is a sample configuration of CORS and a description of its XML elements:

<CORSConfiguration>
    <Enabled>true</Enabled>
    <Access-Control-Allow-Origin>https://localhost:9443,http://localhost:9763</Access-Control-Allow-Origin>
    <Access-Control-Allow-Headers>authorization,Access-Control-Allow-Origin,Content-Type</Access-Control-Allow-Headers>

    <!--Configure Access-Control-Allow-Methods-->
    <Access-Control-Allow-Methods>GET,POST,PUT,DELETE,OPTIONS</Access-Control-Allow-Methods>

    </CORSConfiguration>

Creating an API

1. Log in to API Publisher Web interface (https://localhost:9443/publisher), and go to Add API page. Create new API with following information.
   
   
   • Name: FindFeeds
   • Context: /feeds
   • Version: 1.0.0
   • Appropriate image as the thumbnail
   • Endpoint: http://gdata.youtube.com/feeds/api/standardfeeds
   • Tiers: Gold, Silver, Bronze (select all 3 – this field supports multiple values)
   • Business owner: Bruce Wayne
   • Business owner e-mail: dark.knight@wayne-enterprises.com
   • Technical owner: Peter Parker
   • Technical owner e-mail: spidey@dailybugle.com
2. Define API resources for the operations you need to perform.
   

   Specify None as the Auth Type of OPTIONS

   For each 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 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.

   

3. Publish the API to the API Store.

Invoking the interactive documentation

1. Log in to the API Store Web interface (https://localhost:9443/store) and click the API published before (FindFeeds).
2. The API opens. Under the API Console tab, you can find the interactive documentation for FindFeeds.
3. Click on GET operation of 'feeds/1.0.0/top_rated' to expand it. There, you can enter the Authorization Headers, Parameters and click Try it out to invoke.
4. The response appears. For example,
   

Updating the API definition

The API creator can update/customize the automatically generated API definition for each API.

1. In the API Publisher, go to the Doc tab of FindFeeds API to see its API definition. Click Edit Content.

2. API definition contains the JSON representation of the API. You can easily modify existing content, add/remove elements, change paths and parameters etc. using the JSON editor.

   • API Manager 1.5.0 onwards has integrated JSONMate as the editor for modifying the API Definition.
   • For the Swagger specification of API declaration, see https://github.com/wordnik/swagger-core/wiki/API-Declaration.

3. There are Two ways to modify the API Defnition. You can either use the Text Editor given, or the graphical tree editor.

   By default, all the POST and PUT operations have the Payload parameter, which you can use to send any payload when invoking the API. The GET, DELETE operations have Query parameters, which you can use to send URL-appended parameters (ex: v=2&length=200). You can also add named parameters. For example, to modify the path of the API created above with a parameter, edit the path and add the relevant parameter.

   Let's say that you want to send a query parameter called 'v' in the GET request of top_rated resource. The screenshot below shows path modified with a parameter. Also, the default Query Parameter is changed to a parameter called v .

   Text Editor

   You can just modify the JSON content according to Swagger Specification.

   

   Graphical Editor

   Shown below is an example of the graphical editor. To add new elements, click Add New Value and provide the value. To delete elements, delete the value of Key. For example, if you delete the Key value named description, that element will be deleted. Also be sure to modify descriptions, notes, summary on each of the operations.

   

    

4. Once the modifications are done, save.

5. Log in to the API Store and click on GET operation to expand it. There you can enter the parameters and try it out.
   

Next, see API Versioning.