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

All docs This doc

Versions Compared

Key

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

...

  1. Log in to API Publisher Web interface (https://localhost:9443/publisher), and go to Add API page. Create new API with following information.

  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 /phoneverify/1.0.0 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.

    Image RemovedImage Added

  3. Publish the API to the API Store.

...

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

Updating the API definition

...

  1. In the API Publisher, go to the Doc tab of PhoneVerify API and click Edit Content under Swagger Documentation.
    Image Removed Image Added
  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. A sample API definition is given below:

    Code Block
    {
        "apiVersion": "1.0.0",
        "swaggerVersion": "1.1",
        "basePath": "http://10.100.5.123:8280",
        "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"
                            }
                        ]
                    }
                ]
            }
        ]
    }
    
    Info
  3. 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. You can use the Query parameters in GET, DELETE operations to send URL-appended parameters (e.g.,: v=2&length=200). You can also add named parameters. For example, to modify the path of the API created above, edit the path and add the relevant parameter. I.e., if 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 RemovedImage Added

    Image Removed Image Added 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 RemovedImage Added

     

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

Next, see Adding Documentation Using Swagger.