Adding Documentation Using Swagger
- Former user (Deleted)
- Former user (Deleted)
Providing Interactive Documentation support helps users to clearly understand and experience the APIs. WSO2 API Manager provides this functionality through the integration with Swagger. Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. In Swagger, when APIs are described in simple static JSON representation, they can be loaded through Swagger UI which in turn provide the 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 will be automatically generated and saved into the registry as "API Definition". This "API Definition" is describing the API with the information provided at the API creation level.
This "API Definition" of a particular API can be modified from the "Doc" tab. In API Store level, Swagger UI discovers the "API Definition" for each API and displays the interactive documentation under API's "Overview".
Let's see step by step how to get an Interactive documentation for the API, FindTweets which is based on the on-line search functionality provided by Twitter (http://search.twitter.com). Please note that we will be using http://search.twitter.com/search.atom as the Production Url/Endpoint
Create API
Log in to API Publisher, and Go to Add API Page. Create new API with following information.
- Â Â Â Name: FindTweets
- Â Â Â Context: /twitter
- Â Â Â Version: 1.0.0
- Â Â Â Appropriate image as the thumbnail
- Â Â Â Endpoint: http://search.twitter.com/search.atom
-    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
Define the API resources for the operations you need to perform.
Allow OPTIONS with None Auth Type
For each of the resource which has HTTP verbs requiring Authentication (Auth Type is not NONE), make sure to enable OPTIONS with None Auth type. For example as following screen shot shows, resource with /* URL Pattern has HTTP verbs with "Application & Application User" Authentication type. So we should allow OPTIONS with None Auth type.
This is to support CORS (Cross Origin Resource Sharing) between API Store and Gateway. But in case, no Authentication is needed for any of the HTTP verbs, it is not required to allow OPTIONS with None Auth type.
Save the API
Invoke an API
Go to API Store and go to the above published FindTweets API. There under API Try It tab you can find the interactive documentation for FindTweets.
Now click on GET operation to expand it. There you can enter the Authorization Headers, Parameters and Try it out.
Now when you click on Try-it, the response will appear.
Â
Updating API Definition
We can update/customize the automatically generated API definition for each API. For that go to "Doc" tab of FindTweets API. There you can find the API Definition which containing the JSON representation of the API. So if you want to do any modifications to Paths, Parameters, descriptions etc you can do it by editing the API Definition.
Please find the Swagger Specification for API Declaration from here.
By default, all the operations will have the Payload parameter, which you can used to send any payload when invoking the API. If you want, you can add any specific named parameters. For instance for the above created API, if you want to modify the path with a parameter, then you can edit the path & add the relevant parameter.
Below the auto genearted API Definition, updated with resource path and named parameter to invoke the API.
{
"apiVersion": "1.0.0",
"swaggerVersion": "1.1",
"basePath": "http://localhost:8280",
"resourcePath": "/tweets",
"apis": [
{
"path": "/tweets/1.0.0?q={param}",
"description": "no-info",
"operations": [
{
"httpMethod": "GET",
"summary": "FindTweets",
"nickname": "getTweets",
"parameters": [
{
"name": "Authorization",
"description": "Access Token",
"paramType": "header",
"required": true,
"allowMultiple": false,
"dataType": "String"
},
{
"name": "param",
"description": "Query String",
"paramType": "path",
"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": "Payload",
"description": "Request Payload",
"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"
}
]
}
]
}
]
}
As you can see path has been modified with a parameter.
"path": "/tweets/1.0.0?q={param}"
Also parameter definition has been added for param and the default Payload parameter is removed
"parameters": [
{
"name": "param",
"description": "Query String",
"paramType": "path",
"required": true,
"allowMultiple": false,
"dataType": "String"
}
]
Also make sure to modify descriptions, notes, summary on each of the operations.
Now save the required modifications and Publish the API.
Now click on GET operation to expand it. There you can enter the parameters and Try it out.
Next, see API Versioning.