Edit and Consume APIs using Swagger Tools

WSO2 API Manager has an integrated Swagger Editor, 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 Editor 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 Editor 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 Editor.

API Manager supports for both Open API 3.0 and Open API 2.0 specifications and you can simply create, import, edit and consume the APIs defined in both specifications.

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

This tutorial uses the PhoneVerification API created in Create and Publish an API.

Sign in to the WSO2 API Publisher and choose to design a new REST API.
https://<hostname>:9443/publisher

You can select the Open API specification version when you start creating a new REST API. To see the options click Show More Options. Select the supported API specifications from the drop-down list.
Click Start Creating.
In the Design tab, give an API name, a context and a version, and click Edit Source under the API Definition section.
The Swagger UI opens.
Add a GET and POST method for the API.
1. Add the following code under the paths object as shown in the screenshot.
  In the code below, 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  
```
  Troubleshooting
  
  If you get an error after adding the API definition in the Swagger UI, first check the indentation of the code that you added, which defines the API, because Swagger throw errors if the indention is not correct.
2. Click Apply Changes.
  This adds a resource with two HTTP methods into the API which is visible in the WSO2 API Publisher.
Let's assume that 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.
Change the response content type to XML.
1. Click Edit Source and add the following code under the GET method.
```
produces:
        - text/xml
```
2. Click Apply Changes.
  The response content type that you updated is visible when you expand the GET method in the WSO2 API Publisher.
  You can use this attribute to document the type of the response message that the backend sends. It does not do any message type conversion. You can add multiple values as a comma-separated list.
  Example:
  produces: - text/xml, application/json

Define parameters that correspond to the GET method.

Click Edit Source and add the following code, which defines two parameters to the method, under the GET 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

Click Apply Changes.
The two parameters with their descriptions that you added are visible when you expand the GET method in WSO2 API Publisher.

Add a summary and description for the GET method.
1. Click Edit Source and add the following code, which defines a 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."
```
2. Click Apply Changes.
  The summary and description of the GET method that you added is visible when you expand the GET method in WSO2 API Publisher.
Add parameters to the POST method and also change the POST method datatype.
1. Click Edit Source and add the following code under the POST method, which defines two parameters named PhoneNumber and LicenseKey to pass in the payload. 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
```
2. Click Apply Changes.
  The two parameters with their descriptions that you added are visible when you expand the POST method in WSO2 API Publisher.
Change the title of the API.
1. Click Edit Source, and add the following code in the Swagger UI.
  This is the title that is visible to the consumers in WSO2 API Store after the API is published.
```
info:
  title: PhoneVerificationAPI
```
  You can see how this change is reflected in the WSO2 API Store in step 15.
2. Click Apply Changes and complete the API creation process.
Complete the rest of the API creation process.
For more information, see step 6 onwards under Create and Publish an API.
Click Go to APIStore and click on the API that you just published.

The API opens.
Click API Console.
Note that the changes that you made earlier are now appearing in the WSO2 API Store for consumers.

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