How to create swagger documentation for REST API

Intermediate | 45 Minutes

API Gateway Enterprise Integration

Overview

To use an ION API connection point in ION Connect, you must first register an ION API Suite in the API Gateway with Swagger 2.0 or Open API documentation. However, not all APIs available online come with the necessary documentation, and in some cases, you may need to create it manually.

Tutorial

Swagger documentation is used for REST APIs, while WSDL documentation is for web services. Swagger outlines the HTTP verb methods (GET, POST, PUT, PATCH, DELETE), along with the request and response parameters and their types. For more information, refer to the official Swagger documentation. Many free REST APIs lack proper documentation—one example is an API for Exchange Rates, which we will create in this tutorial.

To accomplish this, you'll use a free tool called Swagger Editor, an online platform designed to help you create accurate API documentation. Here are the steps we'll follow:

• Create an Account and API Key.
• Choose the endpoint you want to document.
• Create the swagger documentation (swagger editor).
• Test the documentation (swagger editor).
• Register the custom API suite and upload the documentation.
• Test the documentation (API Gateway).

1. Create an Account and API Key

The free API is protected by an API Key. To create the API Key you need to register an account.

Open a browser and go to this URL and provide Name, Email, Password, and Confirm Password and click on the Register button to create a new account.

Check your email and confirm your subscription.

Once verified, you are logged in and the API Key is created for you.

2. Choose the endpoint you want to document

When you are logged in, click the Docs link and then select Documentation .

Scroll down and on the left bar, select Latest Rates Endpoints .

You reached the endpoint description, which outlines the parameter specifications , their types ( optional or required ), and provides an example of the API response .

You can test it directly in your browser, by opening a new tab and pasting this URL :

https://commodities-api.com/api/latest ? access_key = API_KEY & base = USD & symbols = GBP,JPY,EUR Replacing the API_KEY with your API Access Key generated when you have created your account.

3. Create the swagger documentation (swagger editor)

Once you identified the endpoint for which you want to create the documentation, it's time to create it.

Open a new tab in your browser and go to this URL: Swagger Editor. You will see the page below.

This is the default example of Open API documentation for a Petstore API. Your goal is to create Swagger 2.0 documentation for your endpoint.

You wonder what is the difference between Open API and Swagger 2.0 documentation. Mainly there are 2 differences.

• Swagger 2.0 is the old definition for REST API and it is written in JSON format.
• Open API 3.0.X is the new definition for REST API and it is written in YAML.

There are also tools that convert Swagger 2.0 to OpenAPI 3.0 and vice versa. Your goal will be to write Swagger 2.0 documentation and also see how to convert to OpenAPI 3.0.

Select and remove everything from the editor, and you will see this page.

You will be creating 4 parts:

• info
• schemes
• paths
• definitions

3.1 info

In the "info" section, you have to provide the title , description , and version of the documentation, plus the host and the basePath of the endpoint. You will receive an error which you will fix later on.

3.2 schemes

In the "scheme" section, you have to provide the protocol [HTTP,HTTPS], in your case you have only HTTPS . You still have the same error which you will fix later on.

3.3 paths

In the "paths" section, you define the final part of the endpoint URL, specify the HTTP verb methods (such as GET, POST, PUT), and outline the parameters, including their types, as well as the structure for request and response bodies.

3.4 definitions

This part can be the most challenging, as it requires familiarity with JSON schema definitions. In this section, you define the types for the Request and Response payloads. In your case, since you're using the GET method rather than POST, there is no request payload to define, but you will need to create the schema for the Response payload.

For the Request, you’ve already defined the types in the parameters section. If not, you’ll need to create a new definition here. As you can see, these definitions can be quite complex, but we'll explore how to simplify the process. Since you’re working with a GET verb method, you can easily use your browser for testing. However, for POST verb methods, you'll need to use a client like Postman to make the API call.

Make the API call as generic as possible providing only mandatory values, in your case provide the API_KEY . The other parameters are optional. Copy the output.

Now you have to create a JSON schema for this JSON Object. You can find free tools on the internet like this one, copy the output and generate the schema.

Copy the generated schema and use it in the Swagger documentation. Remove the $schema line from the generated schema, give a Name to the definition and paste the JSON Schema.

4. Test the documentation (swagger editor)

Now that you have created the swagger documentation, let's test if it works. On the right side of the page editor expand the GET endpoint, click TRY IT OUT , provide the required parameter ( API_KEY ) and click the EXECUTE button. Check that the response is the same as the response you have received in your browser.

5. Register the custom API suite and upload the documentation

You have created a working Swagger 2.0 documentation for the free API, now let's try to use it in the API Gateway. To do that you have to create a New custom API Suite and upload the Swagger 2.0 documentation.

5.1 Register the custom API suite

Log into the Infor OS Portal and click the API Gateway menu label on the top bar.

Click the ( +Add ) tile to create a New API suite.

On the next page, click on the ( + Create New ) button.

Fill in all mandatory input and then click the ( + ) button below Target Endpoints tab.

Provide the Target Endpoint URL , the Target Endpoint Description , and the Proxy value (any value you like). Click Save .

• Target Endpoint URL - https://commodities-api.com/api
• Target Endpoint Description - Latest Rates
• Proxy value - proxy

Now you are ready for uploading the Swagger documentation.

5.2 Upload the documentation

Before uploading the Swagger 2.0 documentation, you have to apply a small modification.

The reason for this modification is that now the host and basePath are managed by the API Gateway and the basePath of the documentation is now related to the New custom API suite. Change the basePath to the correct path. (see the photos above).

Now that you have applied this modification, click on File and Save as JSON and store the file in a local folder. You may also notice the option to convert and save the file in YAML format. If you click on the Edit menu, there is the option to convert the swagger 2.0 documentation to OpenAPI3 as we discussed before.

On the Commodities API screen, under the Endpoints tab. Click on the Documentation icon.

You arrive at a new Proxy page, Scroll down to the Documentation tab and click the ( + ) button, on the Add Documentation page, provide a Name , from the drop down select Swagger as a Type and in the Enter URL or Upload Swagger JSON/YAML field select the JSON file you created with the Swagger editor. Click Save . The new custom API suite now has its own Swagger documentation.

6. Test the documentation (API Gateway)

Let's test now the custom API in the API Gateway. From the document tab, expand the resource definition, click the Try it out button, enter the API_KEY and click the Execute button. Check if the response is the same as what you get from the swagger editor and from the browser. You have created a swagger 2.0 documentation and you have registered a new API Suite, now you can use it in the API connection point of the ION Connect.