Why you should write API Documentation
“Why do we need to write documentation?”
“C‘mon, why waste time on that instead of coding it? “
You’ve probably heard these expressions before, when someone mentioned that it is important to write documentation.
Yeah, we know… writing good documentation takes time, it’s boring comparing to coding, but it makes developers lives easier.
Here we will be focusing on API documentation. So let’s begin with what API documentation is, why should we write it and why it matters.
What is API Documentation?
API documentation is a technical content deliverable, containing instructions about how to effectively use and integrate with an API. It’s kind of a manual containing all the information required to work with the API, with details about the functions, classes, return types, arguments and more.
API definition is language-agnostic, so you can take advantage from it independent of the language that you choose to do the implementation.
Your API definition should serve as the source of truth for your API implementation.
Nowadays, the most commonly used definition for APIs is the OpenAPI Specification. The OpenAPI Specification (OAS) defines RESTful standards for APIs. And the definitions using it, map resources and operations for an API.
Why do we write API Documentation?
Even though working with Agile, and one of the principles being “Working Software Over Comprehensive Documentation”, from Agile Manifesto, documentation matters, and we invest our time doing it. Why? Take a look to the following points:
- Improves the experience for developers using our API;
- Decreases the amount of time spent on-boarding new users (internal developers or external partners). New users will start being productive earlier and will not depend on a person (already with the knowledge) who would need to spend slots of their time to explain how the API is design and how it works;
- Leads to good product maintenance and quicker updates. It helps your internal teams know the details of your resources, methods, and their associated requests and responses, making maintenance and updates quicker;
- Agreement on API specs for the endpoints, data, types, attributes and more. And this helps internal and external users to understand the API and know what it can do;
- The API contract can act as the central reference that keeps all the team members aligned on what your API’s objectives are, and how the API’s resources are exposed;
- Unblocks development on different sides (front-end / back-end / mobile development) due to dependencies on specification;
- Allows identifying bugs and issues in the API’s architecture when defining it with the team;
- Decreases the amount of time (and headaches!!!) spent on understanding how the API works and deciphering unexpected errors when using it.
Besides the points noted above, other advantages of documenting your APIs are that you can generate implementation code, make your APIs live and monitoring them.
You can have the best, functional product, but no one will use it if they don’t know how to.
Why have we chosen Swagger ?
Swagger is a powerful yet easy-to-use suite of API developer tools for teams and individuals, enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
- It is simple to use, to design and model APIs according to specification-based standards (OpenAPI specification);
- It has a good interface and helps improving developer experience with interactive API documentation;
- Performs simple functional tests;
- It is stable, it’s possible to reuse code;
- It has good integration plugins with Code Editors;
- It has pro and open source tools.
SwaggerHub: The design and documentation platform for teams and individuals working with the OpenAPI Specification
Swagger Inspector: Easily test and try out APIs right from your browser, and generate OpenAPI Specification definitions in seconds
Swagger Editor: API editor for designing APIs with the OpenAPI Specification
Swagger UI: Visualize OpenAPI Specification definitions in an interactive UI
Swagger Codegen: Generate server stubs and client SDKs from OpenAPI Specification definitions
How to document APIs: Design First vs Code First
At Evodeck Software, where I’m working, we have been implement the Design First approach. Why do we do it? Because all the points mentioned in Why do we write API Documentation? section. It makes developers life easier and unblocks the development in both sides (front-end and back-end) once the specification is defined and aligned on the team.
There are advantages and disadvantages associated with both approaches, but let’s take a quick look on both of them:
Design First
The Design First approach advocates for writing your API definition before writing any code.
An effective API design helps you and all members involved quickly understand your API’s resources and value propositions, reducing the time taken for them to integrate with your API.
Identifying design issues before writing any code is more efficient than catching issues after the implementation is done.
And once you’ve created your definition, you can create implementation code for your API. With a good design it’s easier to split the implementation tasks among the developers. And then they can implement the API themselves or using the tools (Swagger Editor for example) to create the implementation code.
Code First
The Code First approach advocates for writing implementation code first before designing and writing your API definition.
This approach ensures that your definition is consistent with your implementation. But you need to make sure the definition has human-friendly descriptions and examples.
If you follow this approach, there are tools and packages that allow you to generate documentation from existing APIs:
- Swagger tools (Swagger Editor or Swagger Inspector)
- Nancy.Swagger it is a Nancy plugin that generates API documentation
- SwashBuckle is a .NET library
How does it look like to write an API Documentation using Swagger?
Let’s build a simple example of an API Documentation for a book store using Swagger Editor (using OpenAPI 3.0.0 — OAS3 is still working in progress, so not all the functionalities are available yet but you can use a smaller version such as OAS/Swagger 2.0):
If you define your server url on the API definition, you can test it right away. And using this tool you can also generate the implementation code.
Conclusion
So there are a lot of reasons to design APIs. Whether for internal and external (teams / systems) alignment or to discover and discuss the solution for impediments and/or issues . At Evodeck Software, where I am, writing documentation has been part of all our projects and will continue to be, since it has brought the advantages already mentioned here.
There are a lot of tools that you can use for that, no matter if you go with Design First or Code First approach. Here we used Swagger, which gives you a variety of tools depending on your approach. Give it a try, lets elevate the Developer Experience (DX) with good API documentations, lets design APIs!!!
