API Lifecycle Basics: Documentation
API Lifecycle Basics: Documentation
Documentation is often a point point in software development. Find out just how crucial documentation is for APIs and how to craft those docs in a less painful way.
Join the DZone community and get the full member experience.Join For Free
Learn more about how to Prevent Slow or Broken APIs From Affecting Your Bottom Line.
API documentation is the number one pain point for developers trying to understand what is going on with an API, as they work to get up-and-running, consuming the resources they possess. From many discussions I’ve had with API providers, it is also a pretty big pain point for many API developers when it comes to trying to keep up to date, and delivering value to consumers. Thankfully, API documentation has been being driven by API definitions like OpenAPI for a while, helping keep things up to date and in sync with changes going on behind the scenes. The challenge for many groups who are only doing OpenAPI to produce documentation, is that if the OpenAPI isn’t used across the API lifecycle, it will often be forgotten, recreating that timeless challenge with API documentation.
Thankfully, in the last year or so, I’m beginning to see more API documentation solutions emerge, getting us beyond the Swagger UI age of docs. Don’t get me wrong, I’m thankful for what Swagger UI has done, but, then, I’m finding it to be very difficult to get people beyond the idea that OpenAPI (formerly known as Swagger) isn’t the same thing as Swagger UI, and that the only reason you generate API definitions is to get documentation. There are a number of API documentation solutions to choose from in 2018, but Swagger UI still remains a viable choice for making sure your APIs are properly documented for your consumers.
- Swagger UI - Do not abandon Swagger UI, keep using it, but decouple it from existing code generation practices.
- Redoc - Another OpenAPI driven documentation solution.
- Read the Docs - Read the Docs hosts documentation, making it fully searchable and easy to find. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar.
- ReadMe.io - ReadMe is a developer hub for your startup or code. It’s a completely customizable and collaborative place for documentation, support, key generation, and more.
- OpenAPI Specification Visual Documentation - Thinking about how documentation can become visualized, not just text and data.
API documentation should not be static. It should always be driven from OpenAPI, JSON Schema, and other pipeline artifacts. Documentation should be part of the CI/CD build process and published as part of an API portal lifecycle as mentioned above. API documentation should exist for ALL APIs that are deployed within an organization and used to drive conversations across development as well as business groups – making sure the details of API design are always in as plain language as possible.
I added the visual documentation as a link because I’m beginning to see hints of API documentation moving beyond the static, and even dynamic, realm, and becoming something more visual. It is an area I’m investing in with my subway map work, trying to develop a consistent and familiar way to document complex systems and infrastructure. Documentation doesn’t have to be a chore, and when done right it can make a developer's day brighter, and help them go from learning to integration with minimal friction. Take the time to invest in this stop along your API lifecycle, as it will help both you and your consumers make sense of the resources you are producing.
Published at DZone with permission of Kin Lane , DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.