Updating API documentation using Swagger- Add a custom header

Posted: August 23, 2014 in Uncategorized
Tags: , , , ,

In order to understand and test APIs created, WSO2 API manager provides interactive documentation. WSO2AM incoparates swagger[https://developers.helloreverb.com/swagger] for this puprpose.In Swagger, we can define a API using a static JSON file. In APIM, when we create an API, it automatically generates the JSON representation of the API which is loaded by the Swagger. In this tutorial, let’s see how we can edit the JSON representation in order to add some custom header to when calling the API. Below are the steps that are going to do in this tutorial.

  • create an API
  • Use Swagger to invoke the API
  • Describe Swagger documantation
  • Edit Swagger documentation to add a custom header named “username”
  • Invoke the API using Swagger with the newly added header

 

Step1 : Create an API

Design API

 

APi Design

APi Design

Implement API

api-implement

Manage API

api manager

 

Swagger doc.

To view the swagger documentation
Locate to APIM store  ->select the API -> Click on “API Console” tab.

swagger doc

Here you see a header called “Authorization” and a query parameter named “Query Parameter”. However if you want to add another header or query parameter, you have to edit the Swagger documentation of the API.

 

Step2:

Edit Swagger doc

To edit the Swagger documentation
Locate to APIMPublisher -> Select API -> click Docs tab -> Edit Content link

edit

 

swagger doc edit

 

Below is the existing JSON representation of the API we created.

{
    "apiVersion": "1.0.0",
    "swaggerVersion": "1.1",
    "basePath": "http://192.168.122.1:8280",
    "resourcePath": "/swagger",
    "apis": [
        {
            "path": "/swagger/1.0.0/users",
            "description": "",
            "operations": [
                {
                    "httpMethod": "GET",
                    "summary": "",
                    "nickname": "",
                    "parameters": [
                        {
                            "name": "Query Parameters",
                            "description": "Request Query Parameters",
                            "paramType": "body",
                            "required": false,
                            "allowMultiple": false,
                            "dataType": "String"
                        },
                        {
                            "name": "Authorization",
                            "description": "OAuth2 Authorization Header",
                            "paramType": "header",
                            "required": false,
                            "allowMultiple": false,
                            "dataType": "String"
                        }

                    ]
                }
            ]
        }
    ]
}

Under parameters section you can see the already defined header “Authorization”. Let’s add another header “username” by adding the below parameter definition under the “parameters” section.

		{
                            "name": "username",
                            "description": "username of the user",
                            "paramType": "header",
                            "required": false,
                            "allowMultiple": false,
                            "dataType": "String"
                        }

After adding the header representation, whole Swagger documentation of the API is

{
    "apiVersion": "1.0.0",
    "swaggerVersion": "1.1",
    "basePath": "http://192.168.122.1:8280",
    "resourcePath": "/swagger",
    "apis": [
        {
            "path": "/swagger/1.0.0/users",
            "description": "",
            "operations": [
                {
                    "httpMethod": "GET",
                    "summary": "",
                    "nickname": "",
                    "parameters": [
                        {
                            "name": "Query Parameters",
                            "description": "Request Query Parameters",
                            "paramType": "body",
                            "required": false,
                            "allowMultiple": false,
                            "dataType": "String"
                        },
                        {
                            "name": "Authorization",
                            "description": "OAuth2 Authorization Header",
                            "paramType": "header",
                            "required": false,
                            "allowMultiple": false,
                            "dataType": "String"
                        },
{
                            "name": "username",
                            "description": "username of the user",
                            "paramType": "header",
                            "required": false,
                            "allowMultiple": false,
                            "dataType": "String"
                        }

                    ]
                }
            ]
        }
    ]
}

New Swagger Doc

new swagger

 

Now add the new header name to Access-Control-Allow-Headers section of repository/conf/api-manager.xml as below

<Access-Control-Allow-Headers>authorization,Access-Control-Allow-Origin,Content-Type, CustomHeader</Access-Control-Allow-Headers>

 

HTTP request before and after

Request to the API before

udara@udara$ nc -l 7777
GET http://localhost:7777/users HTTP/1.1
Accept: */*
Host: localhost:7777
Connection: Keep-Alive
User-Agent: Synapse-PT-HttpComponents-NIO

Request to the API after adding the header to the Swagger documentation

udara@udara$ nc -l 7777
GET http://192.168.122.1:7777/users HTTP/1.1
username: udara
Accept: */*
Host: 192.168.122.1:7777
Connection: Keep-Alive
User-Agent: Synapse-PT-HttpComponents-NIO

 

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s