Edit an API Using the Swagger UI

WSO2 API Manager has an integrated Swagger UI, which is part of the Swagger project. 

Swagger is a 100% open source, standard, language-agnostic specification and a complete framework for describing, producing, consuming, and visualizing RESTful APIs, without the need of a  proxy or third-party services. Swagger allows consumers to understand the capabilities of a remote service without accessing its source code and interact with the service with a minimal amount of implementation logic. Swagger helps describe a service in the same way that interfaces describe lower-level programming code. 

The Swagger UI is a dependency-free collection of HTML, JavaScript, and CSS that dynamically generate documentation from a Swagger-compliant API. Swagger-compliant APIs give you interactive documentation, client SDK generation and more discoverability. The Swagger UI has JSON code and its UI facilitates easier code indentation, keyword highlighting and shows syntax errors on the fly. You can add resource parameters, summaries and descriptions to your APIs using the Swagger UI.

Also, see the Swagger 2.0 specification.

In this tutorial, let's see how you can add interactive documentation to an API by directly editing the Swagger code and through the API Publisher UI.

1. Log in to the API Publisher and choose to design a new API.
   
2. In the Design tab, give an API name, a context and a version, and click the Edit Source button under the API Definition section.
   

3. The Swagger UI opens. Add the following code under the paths object. It adds a resource with two HTTP methods into the API.

   Tip:

   In the below code, note that you have a resource defined with the URL pattern /CheckPhoneNumber under the paths object. This is followed by the HTTP methods GET and POST. For each HTTP method, the following parameters are defined.

   • responses: An object to hold responses that can be used across operations. See the Swagger specification for details.
     
   • x-auth-type: WSO2-specific object to define the authentication type of the method.
   • x-throttling-tier: WSO2-specific object to define the throttling tier of the method.

    

   /CheckPhoneNumber:
       get:
         responses:
           '200':
             description: ''
         x-auth-type: Application & Application User
         x-throttling-tier: Unlimited
       post:
         responses:
           '200':
             description: ''
         x-auth-type: Application & Application User
         x-throttling-tier: Unlimited  

   
   

4. Click Apply Changes. Back in the API Publisher, note that a resource with two HTTP methods are added to the API.
   
   Let's say the backend of this API sends the response in XML format. Let's document this under the GET method in the resource that we just added. 

5. Click Edit Source and add the following code under the GET method.

   produces:
           - text/xml

   

6. Click Apply Changes. Back in the API Publisher, expand the GET method and note that the response content type has changed to XML. 

   Tip: You can use this attribute to document the type of the response message that the backend sends. It doesn't do any message type conversion. You can add multiple values as a comma-separated list. E.g.,

   produces:
- text/xml, application/json

   

7. Click Edit Source and add the following code under the GET method. It adds two parameters to the method.

   parameters:
           - name: PhoneNumber
             in: query
             required: true
             type: string
             description: Give the phone number to be validated
           - name: LicenseKey
             in: query
             required: true
             type: string
             description: Give the license key as 0 for testing purpose

   

8. Click Apply Changes. Back in the API Publisher, note the two parameters with their descriptions that are added under the GET method.
   

9. Click Edit Source again and add the following summary and description to the GET method.

   summary: Check the validity of your phone number
   description: "Phone Verification validates a telephone number and returns carrier information, location routing etc."

   

10. Click Apply Changes. Back in the API Publisher, note the summary and description appearing under the GET method.
    

11. In the Swagger UI, add the following code under the POST method. It adds two parameters as PhoneNumber and LicenseKey to pass the payload in. It also changes the datatypes of the parameters to application/x-www-form-urlencoded as the backend expects that datatype.

    consumes:
            - application/x-www-form-urlencoded
          parameters:
            - name: PhoneNumber
              in: formData
              required: true
              type: string
              description: Give the phone number to be validated
            - name: LicenseKey
              in: formData
              required: true
              type: string
              description: Give the license key as 0 for testing purpose

    

12. Click Apply Changes. Back in the API Publisher, note the parameters that you added are visible under the POST method.
    

13. In the Swagger API, change the title of the API as follows. This is the title that is visible to the consumers in the API Store, after the API is published.

    info:
      title: PhoneVerificationAPI

    
    You will see how this change is reflected in the API Store in step 15. 

14. Click Apply Changes and complete the rest of the API creation process. Once you are done, click Save and Publish on the Manage tab to publish the API to the API Store.
15. Log in to the API Store and click on the API that you just published.
    
16. The API opens. Go to its API Console tab and note the changes that you did earlier now appearing in the API Store for consumers.
    

In this tutorial, you have seen how the integrated Swagger UI can be used to design, describe and document your API, so that the API consumers get a better understanding of what the API's functionality is.