This documentation is for WSO2 API Manager 1.7.0 View documentation for the latest release.
Page Comparison - Adding Documentation Using Swagger (v.5 vs v.24) - API Manager 1.7.0 - WSO2 Documentation

All docs This doc

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


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 under in the API's Overview Documentation tab.

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

Table of Contents

In the examples we discuss here, we use an API named PhoneVerify FindFeeds, which is based on the online search functionality provided by YouTube ( We use 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 (CROSCORS) between the two using CORS configuration in <APIM_HOME>/repository/conf/api-manager.xml file. Given below is a sample configuration of CROS CORS and a description of its XML elements:


XML ElementsValuesDescription
<Enabled>True/FalseUsed to enable/disable sending CORS headers from the Gateway. By default, CORS is enabled (True). This is needed for Swagger to function properly.
<Access-Control-Allow-Origin>HTTP and HTTPS Store Address. Change the Host and Port for correct values of your store. For example, https://localhost:9443,http://localhost:9763 The value of the <Access-Control-Allow-Origin header>. Default values are API Store addresses that are required for swagger to function properly.

Header values you need to pass when invoking the API. For example, authorization, Access-Control-Allow-Origin, Content-Type

Default values are sufficient for Swagger to function.
<Access-Control-Allow-Methods>GET, POST, PUT, DELETE, OPTIONSMethods required to be supported from the Swagger client.


  1. Log in to API Publisher Web interface (https://localhost:9443/publisher), and go to Add API page. Create a new API with following information by navigating to each tab.
    • Name: PhoneVerifyPhoneVerification
    • Context: /phoneverify
    • Version: 1.0.0
    • Tier: Gold, Silver, Bronze (select all 3 – this field supports multiple values)
    • Transports: HTTP/HTTPSChoose to create a wildcard resource (/*)
    • Endpoint type: HTTP
    • Production Endpoint:
    Define API resources for the operations you need to perform.
    Specify None as the Auth Type of OPTIONS
    For each
    • Tier availability: Bronze/Gold/Silver/Unlimited
    • Transports: HTTP/HTTPS
      Image Added

    In the Manage screen, you can specify an authentication type for the methods of the resource that you created earlier. 

    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.

    Image Removed

    Image Added 

  2. Publish the API to the API Store.

Invoking the interactive documentation

  1. Log in to the API Store Web interface (https://localhost:9443/store) using admin/admin and click on the API published before (PhoneVerify).
  2. The API opens. Subscribe to the API and generate an access token. You need it to invoke the API.
  3. Go to the API Console tab. You can find the interactive documentation.
    Image Removed
  4. Click on GET operation of 'phoneverify/1.0.0/' to expand it. There, you can enter the Authorization Headers (use the authorization key that was generated when subscribing to the API), Parameters and click Try it out to invoke


    The response appears as follows:

    Image Removed

Updating the API definition

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

  1. In

    Log in to the API Publisher, go to the Doc tab of PhoneVerify API and click Edit Content under Swagger Documentation.

    Image Removed

    Image Added

  2. The API definition opens. Note that the API definition contains the JSON representation of its JSON representation.

    • By default, all the POST and PUT operations have a Payload parameter, which you can use to send any payload when invoking the API.
    You can easily modify
    • You can use the Query parameters in GET, DELETE operations to send URL-appended values (e.g.,: v=2&length=200).
  3. Modify existing content, add/remove elements, change paths and parameters etc. using the JSON editor. A sample API definition is given below:

    Code Block{ "apiVersion": "1.0.0", "swaggerVersion": "1.1", "basePath": "", "resourcePath": "PhoneVerification", "apis": [ { "path": "/phoneverify/1.0.0/CheckPhoneNumber", "description": "no-info", "operations": [ { "httpMethod": "GET", "summary": "PhoneVerify", "nickname": "getDetails", "parameters": [ { "name": "Authorization", "description": "Access Token", "paramType": "header", "required": true, "allowMultiple": false, "dataType": "String" }, { "name": "Payload", "description": "Request Payload", "paramType": "body", "required": true, "allowMultiple": false, "dataType": "String" } ] }, { "httpMethod": "PUT", "summary": "no-info", "nickname": "no-info", "parameters": [ { "name": "Authorization", "description": "Access Token", "paramType": "header", "required": true, "allowMultiple": false, "dataType": "String" }, { "name": "Payload", "description": "Request Payload", "paramType": "body", "required": true, "allowMultiple": false, "dataType": "String" } ] }, { "httpMethod": "POST", "summary": "no-info", "nickname": "no-info", "parameters": [ { "name": "Authorization", "description": "Access Token", "paramType": "header", "required": true, "allowMultiple": false, "dataType": "String" }, { "name": "Payload", "description": "Request Payload", "paramType": "body", "required": true, "allowMultiple": false, "dataType": "String" } ] }, { "httpMethod": "DELETE", "summary": "no-info", "nickname": "no-info", "parameters": [ { "name": "Authorization", "description": "Access Token", "paramType": "header", "required": true, "allowMultiple": false, "dataType": "String" }, { "name": "Query Parameters", "description": "Request Query Parameters", "paramType": "body", "required": true, "allowMultiple": false, "dataType": "String" } ] }, { "httpMethod": "OPTIONS", "summary": "no-info", "nickname": "no-info", "parameters": [ { "name": "Payload", "description": "Request Payload", "paramType": "body", "required": true, "allowMultiple": false, "dataType": "String" } ] } ] } ] }

    of the API definition using either of the following editors: Text Editor or the Graphical Tree Editor.

  4. There are Two ways to modify the API definition. 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.

    Image Removed

    Image Removed 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.

    Image Removed


  5. Once the modifications are done, save.

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


  1. 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: Image Added

  2. After the modifications are done, click save.


The Swagger JSON files are saved in the following location in the registry: /_system/governance/apimgt/applicationdata/api-docs/<API name>/api-doc.json. To browse the registry, log in to the management console (https://localhost:9443/carbon) as admin/admin and select Resources -> Browse menu.


Invoking the interactive documentation

  1. Log in to the API Store Web interface (https://localhost:9443/store) and click the API published before.
  2. Subscribe to the API using the Bronze tier.
    Image Added
  3. Generate access tokens. You need them to invoke the API in the next steps.
  4. Select the API again and go to the API Console tab, which shows the interactive documentation of the API.

  5. 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.
    Image Added

    Note the following in the above UI:

    Base URLAppears at the bottom of the console. Using the base URL and the parameters, the system creates the API URL in the form http://host:8280/<context>/<version>/<back end service requirements included as parameters>. For example, http://host:8280/phoneverify/1.1.0/CheckPhoneNumber.
    Query ParametersGive 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.
    AuthorizationIn 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.


  6. Note the response for the API invocation that appears as follows:
    Image Added
  7. 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.
    Image Added