How to create swagger documentation for REST API

Business Problem

To use an ION API connection point in ION Connect, you must have registered an ION API Suite in the API Gateway with the Swagger 2.0 or Open API documentation. Not all the APIs you can find on the internet have the documentation available to be used, sometimes you have to create them manually.

---

---

Tutorial

The Swagger documentation is at the Rest API whereas the WSDL documentation is at the web service. It describes the verb methods (GET, POST, PUT, PATCH, DELETE), the Request and Response parameters, and their types. For details about swagger, visit the official documentation. There are lots of free REST APIs without documentation, one of these is an API for the Exchange rate, which we create in this guide.

To do that you will use a free tool that is an online editor to help you in building correct documentation, named swagger editor. These are the steps we follow along:

• 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

Our 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 on the left bar and select Latest Rates Endpoints.

You arrive at the description of the endpoint, where you can find the parameter specification and the type of them [optional, required] and an example of 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 Key generated when you have created your account

---

3. Create the swagger documentation (swagger editor)

Once identified the endpoint for which you want to create the documentation, it’s time to create it. To do that, open a new tab in your browser and go to this URL: Swagger Editor. You will see the below page.

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. Now you can 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, so for your goal, you will write Swagger 2.0 documentation and you will see also how to convert to OpenAPI 3.0.

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

You have to create 4 parts:

• info
• schemes
• paths
• definitions

3.1 info

In the info part, 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 that you fix later on.

3.2 schemes

In the part of the scheme, you have to provide the protocol [HTTP,HTTPS], in your case you have only HTTPS, and you still have the same error above that you fix later on.

3.3 paths

The part of paths is where you have to define the last piece of the endpoint URL, the VERB methods, the parameters, and the types of parameters and requests and responses.

3.4 definitions

This part is the most tricky and difficult to create because you must be familiar with JSON schema definition. in this section, you create the types for the Requests and Responses payload. in your case, you don’t have a Request payload that you can find with POST VERB, whereas here you have the GET VERB, but you have to define the Response payload.

For the Request, you have already defined the types in the Parameters section, otherwise, you have to create a new definition in this section. As you can see the definition can be quite complex and let’s see how you can create it in an easy way. For your goal, you can use your browser because you are dealing with a GET VERB, but in the case of POST VERB, you have to use a client to make an API call like Postman.

Make the API call as generic as possible proving only the mandatory value, 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 the 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 in to the Infor OS portal and click the API Gateway menu label on the top bar

Click the (+Add) tile to create a new suite

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

Fill in all mandatory input and then click the (+) button below Target Endpoint

Provide the Target Endpoint URL, the Target Endpoint Description, and the Proxy value (any value you like) and click on save

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. Now that you have applied this modification (see the photos above), click on File and Save as JSON and store the file in a local folder. If you notice among the option there is also the possibility to convert and save in YAML format. If you click on the Edit menu, there is also the option to convert the swagger 2.0 documentation to OpenAPI3 as we discussed before.

Once clicked on the document icon (see photo above) you arrive at a new page, click the (+) button, provide a Name, select swagger as a type and in the below field select the file created with the swagger editor and click save. The new custom API suite has now 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.

---

Downloads

API Suite & swagger editor definition