Tutorial: How to Write API Documentation using Swagger / Postman / Apidog

The entire process of producing an API from scratch is extremely tedious. Beginning with the "What should my API aim to do?" question, followed by all the code writing and testing, you've finally reached the end of the first API development cycle - publishing.

What is API Documentation and Why is it Important

When releasing your API into the internet and making it available for developers to implement into their applications, there comes a question everyone will ask you. The developers will immediately inquire about how to use your API.

This is why API documentation - good ones - is extremely beneficial for not just you, but everybody who has an interest in your API. The best API documentation is those that developers can understand without consulting you, the API creator, as they can acquire all the required knowledge from the API documentation.

REST API Documentation Overview

REST (Representational State Transfer) is a term used to describe the architectural style that an API follows.

The reason why this article emphasizes REST API is that REST API is one of the most welcomed types of API, mainly recognized for simplifying communication between web applications. REST APIs are also mostly used for background operations on the server side of an application.

Tips for Writing REST API Documentation

REST APIs are not identical to any other APIs. Of course, they have similar variables like HTTP methods and parameters, but REST APIs have some unique characteristics. Your REST API documentation will need adjustments to cover and explain these differences.

Simple Yet Informative

Everyone with varying skills might have an interest in your API, so write your REST API documentation in a way that caters to everyone's knowledge about APIs. Try to avoid jargon as technical vocabulary tends to be hard to understand for the majority of readers.

Common Use Cases

With REST APIs having their distinctive architecture, they also specialize in certain aspects of software: data transfer. With most REST APIs made for internal data processing, it is nice to provide some use cases to demonstrate the function of your REST API.

HTTP Protocol

REST APIs conduct all their communication through the HTTP protocol, unlike other web APIs which can utilize both HTTP and HTTPS protocol. REST APIs also use HTTP methods to transmit information between clients and servers, meaning it is best to elaborate on the HTTP verbs used (GET, POST, PUT, or DELETE).

How to Write RESTful API Documentation

Creating effective API documentation may sound tricky, however, many API documentation tools are available for everyone to use. Additionally, most API platforms, such as Swagger, Postman, and Apidog also provide documentation generators to create API documentation.

The three mentioned API applications (also called API platforms) today can co-create corresponding API documentation while you develop the API itself. You no longer have to regurgitate the entire process and the respective details that entail the APIs you have created!

Using Apidog to Generate REST API Documentation Easily

Apidog is a fairly new but extremely powerful and efficient API design-first development tool. A very intuitive API platform, users can easily understand how to create REST API documentation while working on their projects. But before you begin the start of your Apidog experience, make sure to download the Apidog application first.

To get started with using Apidog, follow these steps below:

Step 1 - Creating an Apidog Account

First, begin by choosing a method to create your Apidog account. You can choose from one of three ways: a Google account, a GitHub account, or an email account. Signing up with Apidog is free, and additional personal information like credit card details is not required in signing up.

Step 2 - Create a New REST API Project in Apidog

Once you have logged in to your Apidog account, you should be able to see the screen above. To create a folder exclusively for your API project, press the "New Project" button around the top right corner of the Apidog app window, and name it according to what you have planned.

Step 3 - Create a New API in your Apidog Project

Inserting Necessary Details About Your API

As you are starting from scratch, start by creating a new API.

In this process of developing your API, make sure to be as complete and competent with the details of your API. Be concise yet thoughtful of the possible type of readers your REST API may attract. Fill out as many blank fields as you can, as they will automatically be part of the generated API documentation Apidog produces.

If you are unsure of how to write API documentation, take your time and allocate some time to read more about what is expected. Asking a friend may greatly help too!

Save Your Work Progress

After working on your API or whenever you think you need to take a break from working, make sure to save your progress by pressing on the "Save" button found around the top right of the screen!

Step 4 - Sharing your REST API Documentation

Arrow 1 - Begin by locating and pressing the "Share" button, found on the vertical bar on the left side of the Apidog app window. You should then be able to see the "Shared Docs" page, which should be empty.

Arrow 2 - Press the "+ New" button under "No Data" to begin creating your very first Apidog REST API documentation.

Select and Include Important API Documentation Properties

Would you like to publish the API on the Internet? Is the API just for your company, or is it a little project you have for yourself? Apidog has the option to choose who can view your API documentation as well as set a file password, so only chosen individuals or organizations can view it.

Once you have included other document information like API documentation name and language, you can press the "Enter" button on your Keyboard, or the "Save" button found at the bottom of the current screen.

View or Share Your REST API Documentation

You now can decide what to do with your API documentation. Apidog compiles your API project's details into an API documentation that is viewable through a website URL. All you have to do is click the "Copy Link" link under "Actions", and you can copy-paste it into your web browser to view it.

In any case you need more details, read this article on how to generate API documentation using Apidog.

Creating REST API Documentation Using Swagger

Like Apidog, Swagger is also pretty straightforward in how it allows API developers or writers to document their API. To edit the most essential parts of API documentation using Swagger, follow the details below.

Arrow 1 - The top portion of the Swagger Editor's left side (the one that looks more like code) is where you can edit the description of the API. Ensure that you provide a clear and simple description for readers to understand by including the API's function, along with a couple of parameters and brief common use cases.

Arrow 2 - The highlighted bottom portion allows you to make changes to the technical, reader-friendly portion of the API documentation. This is where you can edit the API method, parameters, and code samples.

You can also find out in better detail how to use Swagger for REST API documentation here.

Documenting REST APIs Using Postman

Postman provides a friendlier user interface, where the highlighted right-hand side is meant for any additional information about the REST API in development. There are 4 sections that REST API developers can edit to show more details about the API.

• Documentation - You should insert all the important information about your API, such as common use cases, and a brief introduction on what kind of inputs and outputs are expected, along with a description of its utility.
• Comments - On Postman, you can share your API documentation for the public to use and read, and receive feedback or criticism regarding your REST API Documentation. It is a very positive aspect that Postman, as it is very difficult to have the perfect API straight out of production.
• Code Snippets - Postman allows you to prepare code samples for developers to test your API out. You can prepare code snippets for more than a dozen client languages, so prepare as many as you possibly can!
• Request ID - As Postman has mentioned a Postman element can be anything from an HTTP request to an API itself, this section is where the developers can find the specific Request ID for your REST API.

Start Creating Your API Documentation

Although some API platforms like Apidog, Swagger, and Postman may help you create better API documentation, what matters most is that specific, crucial aspects of API documentation are present. Simple language, common use cases, and a direct HTTP protocol are essential for a developer to understand your API!