API documentation helps developers use an API. Keep it current as the API changes, organize it by API type, and make useful examples easy to find. section 5.5.2
Practical ways to improve API documentation:
- Use Swagger to publish documentation updates automatically when API code changes through the deployment pipeline. section 5.5.2
- Organize documentation by API type and add code snippets to support developers using the APIs. section 5.5.2
- Ask internal and external developers for feedback, and consider allowing outside contributions by making documentation open source. section 5.5.2
For a reference document with deep technical detail, include an introduction, a closing summary, and pointers to further reading. section 5.2.3
Keeping API documentation current
When developers said Interswitch’s API documentation was outdated, the team adopted Swagger to publish updates with API deployments. They used Readme to organize documentation by API type and support code snippets. section 5.5.2
