API documentation
You might ask yourself, what is API documentation and why do we need it.
An Application Programming Interface (API) is a software intermediary that allows two applications to talk to each other. Application can refer to a software, while the word interface can be seen as a contract or service between two applications.
In nontechnical terms, an API is the messenger that delivers your question to your friend and returns with the response.
Let’s create a hypothesis: Your friends are computers and your knowledge of them is API documentation.
You have two friends. Bert is a math teacher. Your other friend is called Tim. Tim has family in Germany, with whom he speaks German.
You are at work creating an e-mail to your customer who speaks German. It takes you a long time to write this e-mail and would like someone to look at it and correct it when necessary. This e-mail needs to go out as soon as possible.
Without this API documentation:
You might ask both or none of your friends for an answer, and might struggle with this issue for a longer time.
You might send out this e-mail with mistakes still present.
With API documentation:
You can see Bert can not answer your question (or request) while Tim can. You now know WHO to go to and HOW to ask them. Your mail was corrected and send without any issues or stress.
As we both can see, API documentation can save you a lot of time.
Swagger
Swagger is a technology that allows you to describe and read your APIs structure. With this, we can build an interactive API documentation for every API. Swagger can generate a server stub, client libraries and interactive API documentation. In this article we will dive deeper into Swagger UI which is responsible for API documentation.
This generated documentation looks a little like this:
The general set up of these packages is easy to follow and does not take to long. It is the annotations that take up most of your time if you want the full documentation (parameters, responses etc).
At this moment in time, it is best integrated with Microsoft.
Manual
By manually writing annotations for your endpoints, you are generating the necessary information for Swagger. With this, Swagger can generate a JSON or YAML file which can be used to generate a interactive frontend page which will display your API documentation.
As programmers, we often aren’t a fan of manual work. While a lot of frameworks are interacting with swagger in a clean way, it still takes annotations within every framework.
This annotation looks a bit different in every framework. In Laravel, this looks like:
Automatic
There are developers that worked on packages which uses Swagger UI in a way you don’t need annotation. These packages create your endpoints documentation without annotation. For parameters, responses and more in dept documentation you will however need to annotate.
In .NET: Swashbuckle and NSwag.
These are recommended by Microsoft itself to use.
Laravel: DarkaOnLine
IBM: Swagger UI (more about this below).
Node: swagger-node
Let’s zoom in on the automatic generated code for Laravel. What does this package do? This package starts with your routing. It will use your API file to go over every route and take a good look at the linked method of the linked controller.
This will have an impact when creating routes with resource() or AppSource() commando, in which not every route has a method or controller behind it. This will force you to only create URL routes for existing endpoint. Which I personally find a pro rather than con.
After using the route, it will go to your method and look for annotations for parameters. After doing this for each route, it will generate your JSON file with documentation.
IBM
IBM does not have an automatic package and will need annotations. On top of this, it has some restrictions from IBM itself. Which you can easily find in the following link: https://www.ibm.com/docs/en/app-connect/11.0.0?topic=apis-restrictions-swagger-documents
As API documentation is always a valuable thing to have, as other team members can easily check the endpoints in the documentation of the API for an easier collaboration. (As long as you keep writing annotations when creating new endpoints).
Even though it isn’t automatically generated for IBM, I believe it is still worth to use this or another technology for documenting your API!
