Postcard {4}: Beautiful API Documentation
Developing API? Awesome! Now, you MUST provide a documentation to integrate with it. Check different tools and formats to build the *beautiful* API Documentation that developers will love to use.
The process of developing software has drastically evolved in the last few decades.
On one side, applications have started depending on third-party services for certain functionality and data. And on another side, the application development pattern is moving towards distributed components. Sometimes by separating the front-end and backend, sometimes by breaking down into microservices.
All these changes have brought API and API Documentation to a vital role in the software development process.
In simple terms, API documentation helps developers understand the capabilities of the API and how to integrate it with their own applications.
The API Documentation is the contract between the provider and the consumer of an API.
What an API Documentation should include?
API documentation should include the following information:
Overview: A high-level description of the API, including its purpose, target audience, and any relevant background information.
Endpoints: A list of all the available endpoints, along with a description of their purpose and the input and output formats for each endpoint.
Requests: For each endpoint, the document should include the types of requests that can be made to the API, including the URL structure, HTTP methods, and any query parameters.
Responses: Information on the types of responses that can be expected from each endpoint, including the response format, HTTP status codes, and any error messages.
Authentication: Details on how to authenticate with the API, including any required keys, tokens, or credentials.
Examples: Working examples of how to use the API, including code samples in multiple programming languages.
Error handling: Information on how errors are handled by the API, including any specific error codes or messages that may be returned.
Rate Limiting: Information on any rate limiting or throttling applied to the API, and the consequences of exceeding these limits.
Changes and Versioning: Information on how changes to the API are managed and communicated, including any versioning policies.
Having complete and accurate API documentation can greatly improve the developer experience and encourage wider adoption of the API.
How can we generate a beautiful one?
API documentation can be generated using a variety of tools and processes. Generally speaking, there are 3 common practices -
Generating automatically from the annotations/docblock comments in the source code.
Writing it manually (following a defined structure).
Generating from REST Clients.
Let's see a few examples for each type of API Documentation generator.
Generating automatic API Documentation
The best thing about this process is that it's easy to keep documentation updated with the code changes. And the downside is, sometimes the source code becomes blotted as it needs to contain additional annotations for supporting the documentation.
OpenAPI (formerly Swagger): OpenAPI is an open-source specification for creating API documentation. It is widely supported by various tools, including the popular Swagger UI, which allows developers to interact with an API using a web-based interface easily.
To use Swagger with PHP, see Swagger-PHP.
APIDoc JS: apiDoc creates a documentation from API annotations in your source code. It has support for many languages including Java, JavaScript, PHP, Elixir, Python, and Ruby.
Generating API Documentation manually
These options provide flexibility. Being separated from the source code, you can include any relevant information that may be helpful for API consumers.
API Blueprint: It is a description language for web APIs. You can write your API in this format and can generate beautiful documentation using available tools.
Slatedocs: Slate helps you create beautiful, intelligent, responsive API documentation. It's used by NASA, Sony, Travis-CI, WooCommerce, Coinbase, and many other popular tech companies.
Markdown: You can define a format for your company/team and document APIs in plain markdown. It can be served as a gist, Github wiki, or simply a file in your repository.
If you like this post, please subscribe to receive new posts from BetweenCurlyBrackets immediately. Also, I appreciate a follow on Twitter.
Generating API Documentation from REST Clients
Postman and RapidAPI are two widely used API clients. Both of them support generating documentation from the APIs and collections you test with it.
It's a convenient option when you are already using the REST client for testing your API. It can automatically include the responses (returned by your tests) and code samples in various languages.
My Personal Preference
Previously I was a fan of Symfony NelmioApiDocBundle which generates API Documentation in swagger format. Eventually, started preferring simple markdown with Github Wiki.
Recently, I've started using Slatedocs. It takes the same effort as simple Markdown but provides a far better, beautiful static documentation site.
I've prepared a slim, easy-to-use, Docker-only setup for slatedocs. It's a Github template you can start building with right now.
🐦 Tweet of the week
The following thread has summarized important API best practices beautifully!
🥳 Fun!
When the API Documentation was not followed…
Courtesy: Cover Photo - prisma.io