Proper OpenAPI Documentation - DZone Open Source

Why Do We Need Proper Documentation for Our API Project?

This is the era we are rapidly moving towards with platforms that play the main role in our social and economic activities. This is simply called platform economy. Here APIs are the key instance of the platform. Usually, we know more companies are embracing the API first philosophy. 

If we are keen on achieving our certain business goals through the platform,  we suppose to have a good API project, But if nobody can understand how to use the APIs in our project without any documentation then our project will be useless and won’t be able to reach our economic goal immediately. Because of that, we need to have human-readable API documentation for our project. 

What Is the API Documentation?

API documentation is the technical human-readable blueprint of our API. It contains all the main required details about our APIs such as operation path details, requests body type details, returns types details, arguments for API. In addition to that, we can add examples including the mock inputs and outputs for our API  in the API documentation. Simply we can say API documentation is an entire API structure in your project. 

So If we need to use our APIs by API developers then we need to provide well understandable API documentation for them.  Providing API documentation will lead 

• Increasing awareness about APIs in the project.

• Improving the user adoption of the project (it will help our internal developers to get quickly adapt to the project environment).

• Making it easy to maintain the project by adding, changing APIs. 

These are a few benefits of having  API documentation for the project.

Nowadays most commonly used API definition is OpenAPI Specification (formerly Swagger). I expect that most of you are familiar with OpenAPI, but to whom it is new to have introduction here. Usually, We get used to using it because it is easy to understand, use and design the model APIs.   

“Swagger is a powerful yet easy-to-use suite of API developer tools for teams and individuals, enabling development across the entire API life-cycle, from design and documentation, to test and deployment.”

API Document Generation

If you are a developer who follows the code-first approach and is willing to have your API documentation at the end of the API developments. You will interesting to have a documentation auto-generation tool for your project rather than spending time manually writing your documentation.

Today there are so many code generation tools and frameworks are built to convince developers.

If you are a Ballerina Developer then you can give your try the Ballerina OpenAPI tool for generating your OpenAPI specification to Ballerina APIs. 

Ballerina OpenAPI tooling will make it easy for users to start the development with the code-first approach and design-first approach. You can find more details here.

As a prerequisite, we need to install a ballerina in our machine. Here you can find details about the installation.

Now, we would be using the ballerina to openapi command for generating our API documentation. You can find the various options that are available in this command.

The ballerina to openapi command

• This will generate OpenAPI definition of version 3 including all the API details in the ballerina service with YAML format.

bal openapi -i <ballerina-file> 

• If you need to give a location for the output file you can simply add the `-o` or `--output` to the command with the target directory.

bal openapi -i <ballerina-file> -o <output-file-path> 

• If you need your OpenAPI definition with JSON format you can use the below command for that.

bal openapi -i <ballerina-file> --json 

• Normally in the Ballerina, we can write multiple services inside one ballerina file. For the close view refer to the below code example. It contains two services with base paths `/user` and `/pet`, this time we can select one service to generate one API documentation by using `--service` or `-s` flags to the above command. Other than it will generate API documentation for each service in the ballerina file.

bal openapi -i <ballerina-file> --service /pet

This command will generate API documentation for `/pet` service.

Ballerina code example

import ballerina/http;

listener http:Listener ep0 = new (80, config = {host: "http://petstore.openapi.io"});

type Pet record {

   int petId;

   string name;

   string petType?;

};

service /pet on ep0 {

   # Getting pet by givning petId

   #

   # + id - Pet Id

   # + return - Details about pet

   resource function get pet/[int id]() returns string {

       // API process

       return "hello";

   }

   # Getting all the pets on the list

   #

   # + offset - Number of retriving items

   # + return - list of array 

   resource function get pets(int offset) returns Pet[] {

       // Mock implementation

       Pet p1 = {petId: 1, name: "Tommy", petType: "dog"};

       Pet p2 = {petId: 2, name: "Rova", petType: "dog"};

       Pet[] petArray = [p1, p2];

       return petArray;

   }

}

service /user on new http:Listener(9091) {

   resource function get cachingBackEnd() returns @http:Cache {

       maxAge: 5,

       isPrivate: true,

       privateFields: ["field1", "filed2"],

       noCache: true,

       noCacheFields: ["field03", "fields04"]

   } string|http:Conflict {

       // API implementation ...

       return "Hello, World!!";

   }

}

​

Below openAPI definition is generated openAPI definition for  the above `/pet` service. 

Generated OpenAPI definition

openapi: 3.0.1

info:

 title: Pet

 version: 1.0.0

servers:

- url: "{server}:{port}/hello"

 variables:

   server:

     default: http://petstore.openapi.io

   port:

     default: "80"

paths:

 /pet/{id}:

   get:

     summary: Getting pet by givning petId

     operationId: "operation_get_/pet/{id}"

     parameters:

     - name: id

       in: path

       description: 'Pet Id '

       required: true

       schema:

         type: integer

         format: int32

     responses:

       "200":

         description: Ok

         content:

           text/plain:

             schema:

               type: string

 /pets:

   get:

     summary: Getting all the pets in the list

     operationId: operation_get_/pets

     parameters:

     - name: offset

       in: query

       description: Number of retriving items

       required: true

       schema:

         type: integer

         format: int32

     responses:

       "200":

         description: Ok

         content:

           application/json:

             schema:

               type: array

               items:

                 $ref: '#/components/schemas/Pet'

components:

 schemas:

   Pet:

     required:

     - name

     - petId

     type: object

     properties:

       petId:

         type: integer

         format: int32

       name:

         type: string

       petType:

         type: string

​

You can see this generated OpenAPI definition includes all the parameter details, response details, path details and operation details for ballerina resource functions that bind to `/pet` service. 

Conclusion

In this article, we had a look at why we need API documentation for our APIs. As for how We generate OpenAPI documentation for Ballerina APIs. Hope you may have some sunny ideas about the Ballerina OpenAPI CLI tool for your OpenAPI document generation. You can more learn about the tool here.

During the next article, we will deeply discuss mapping ballerina resource functions details into openAPI definition sections until then happy coding and happy reading.