Mastering your API: Documentation best practices
Having well-defined documentation for our API is essential to make it more accessible to more clients. Because of this, the OpenAPI Initiative (OAI) was born as an open-source community in which industry participants may easily contribute to building vendor-neutral, portable, and open specifications for providing technical metadata for APIs.
OpenAPI Specification
The OpenAPI Specification (OAS) defines a standard to build the documentation. This enables us to develop the API first by writing the documentation instead of starting with the code.
The specification is mainly separated into 5 sections
openapi: this field is required and represent the version number of the specification
info: this object is required and contains some information about the API, as the name, description, version, and others.
paths: this object is probably the biggest one, it is used to add all the information about the endpoints.
components: this element is used to hold the schemas for the document. For example, our request and response object can be a component, and be reusable.
security: this element is used to add information about how to authenticate with the API for those endpoints that require authentication.
These are only a few details of the specification. You can access this free URL to play around with it: https://editor.swagger.io/
Best Practices
1. Clear and Concise Descriptions
Provide clear, concise, and precise descriptions for each endpoint, parameter, and response.
✅ Explain what each endpoint does, the parameters it requires, and what it returns.
❌ Does not document the required parameters and the description of the endpoint
2. Comprehensive Examples
Include multiple comprehensive examples for different scenarios, covering both successful requests and error responses.
✅ Add examples for the input and output scenarios.
@Schema(name = "description", requiredMode = Schema.RequiredMode.REQUIRED, example = "Cat") String animal❌ Provide only one example or omit examples entirely.
3. Consistent and Standardized Format
Use a consistent and standardized format throughout your documentation to maintain clarity and coherence.
✅ Follow OpenAPI specifications to ensure a consistent structure.
❌ Have varying formats for different endpoints, which can confuse users.
4. Detailed Error Handling Information
Document all possible error codes, their meanings, and suggest possible solutions or next steps.
✅ Add all the possible error codes that your endpoint can return and also with examples. If your API is following the RFC 9457, you can also mention it in non-interactive documentation.
❌ Only list error codes without any context or details.
5. Interactive Documentation
Provide interactive documentation that allows users to test endpoints directly within the documentation.
✅ Use tools like Swagger UI and Postman collections to let users execute API calls and see live responses.
❌ Only offer static documentation without any interactive elements.
Additional Tips
Versioning Information: Clearly indicate API versions and document changes between versions.
Define a lifecycle for break change: Sometimes is not possible to avoid break changes. In this case, use versioning to keep the support for the old version and provide clear documentation about the migration plan with the information when the old version is being removed. This is a good way to help API users adapt to newer versions.
Authentication Details: Provide detailed instructions on how to authenticate, including examples of authentication tokens or keys.
Conclusion
By using OAS, we can have a common way to document our API ensuring the non-vendor-lock-in, and making it easier for the consumers and also the developers to understand and evolve the API.
Well-defined documentation for an API is the best way to help customers interact with and use it.
If you like it or want to know more about how you can apply these best practices, please, share a comment here.