Description formats like OpenAPI (Swagger), and open source implementations like Swagger UI, changed the way API teams think about API documentation. By providing a format for defining the operations of your API in a way that is both human and machine readable, and then visualizing those operations to let end consumers interact with the different endpoints of the API — these tools eliminated the need to manually maintain your API documentation.
This has come with obvious benefits for API teams.
Maintaining accurate and up-to-date documentation for your APIs has always been a painful a process. Even organizations and teams that had the luxury of hiring technical writers to work on the API “usage manual” still faced issues when it came to updating documentations with new API versions, Another major benefit is the speed in which description formats, and their supporting tooling, help to generate API documentation. The Swagger UI is the best example for this, allowing users to automatically generate API documentation from the base API design, saving hours of time and developer resources.
Over the last few months, the SwaggerHub team has traveled to events like IBM Interconnect, Microsoft Build, and DockerCon 2017, and time and again heard from developers, technical writers, API designers, DevOps, and other software professionals about how efficient the Swagger UI is for generating useful API documentation. But one of the lessons we’ve also learned from these conversations is that API consumers are expecting a lot more from API documentation, especially in the competitive ecosystem of the API economy.
After all, while generating an interface for your RESTful API is a good first step in providing documentation to your end consumers, it is just the start of what you can do to enable people to understand how to effectively work with your API.
What your API documentation may be missing
Generating a UI for end consumers to work with your API is a critical first step to providing a great API developer experience. But in today’s modern API economy, where APIs are playing a central role in business and strategic growth, documentation needs to go beyond the basic UI.
The goal of generating this UI is to provide a visual resource end consumers can use to easily understand how to work with your API. This is the usage manual for working with your API, and if this usage manual is incomplete and not helpful for consumers, it could directly hurt your consumer’s developer experience and undermine the success of your API program. So it’s important to start thinking about ways to improve the basic Swagger UI and API documentation, that will eventually make for a great developer experience when consuming APIs.
Here are few key sections your API documentation may be missing:
1. Overview Section
If you’re simply generating a basic UI for your API, there’s a good chance your documentation lacks a useful description for people to easily understand what your API does, and why they’d want to work with it in the first place. Provide the necessary information someone would need to understand the value of your API, with an introduction to help them get started. This is the first entry point for potential consumers of your API, so make sure you focus on the value your API provides — what it does, what problems it solves, and what outcomes an end consumers should expect from working with your API. Think about the challenges your consumers are trying to solve when detailing this section. This way, the message of the overview section can really resonate with your target audience.
Here is an example description from our recent SwaggerHub webinar on API developer experience: 
Getting Started Guide
The Getting Started guide can provide information about accessing an API key or client token, as well as the terms of use for working with the API. In addition to your API’s UI, you can include links to other reference material and details for how to contact your team for support, or to share feedback. The guide should hand-hold your consumers to reach success. We recommend drafting guides which can help consumers understand the value of your API in under 5 minutes. Consider this example from SwaggerHub customer, Bandsintown, which publishes its public API docs from SwaggerHub on its website. 
The getting started guide, provides the necessary guidance for getting up and running on the Bandsintown API. There are also helpful examples from companies like Braintree and YouTube, which build out entire help sections for developers to understand how to work with their APIs.
Explanations of Request-Response Cycles
A lot of API teams will do the bare minimum when it comes to describing API endpoints, generating the basic framework needed to visualize the API without adding any real detail to help consumers understand how to work with them. This may have worked before, but in today’s competitive environment with new APIs and solutions coming up every day, consumers have a variety of options to choose from, and they deserve completeness.
Describe the full sample response body in every supported format. This not only includes XML or JSON data formats, but also HTTP headers, error codes, and messages. Having too much information available to help a prospect or end consumer learn to use your API is never a bad idea. Remember that the goal of good API documentation is to provide the necessary information for your target audiences to understand how to work with your API. You should include detailed descriptions, and usage examples when necessary.
If you have technical or domain specific jargon, link that specific item to further documentation explaining these terms. These tactics will ensure clarity and good structure across your API and why certain calls exist, without getting lost in the details of the parameters, headers, and responses.
Links to SDKs and Code Libraries
SDK libraries help consumers integrate faster with your API. They are great for enabling your consumers to easily use your API’s operations and build rich functionality and applications over them. If you already have your API defined with the OpenAPI Specification, you can use a platform like SwaggerHub to generate server side code and client SDKs to help increase adoption of your API.
With one click, SwaggerHub generates the HTML template, with your API’s documentation and 6 client SDK usage examples for your developer portal, making it super easy for your development team to customize, interact and work with. You can always add to the SDKs further to over 30 languages, with SwaggerHub’s in-built codegenerator. 
Do more with your API documentation with SwaggerHub
If you’re already using Swagger to generate an interactive UI for your API, you’re well positioned to take your API documentation to the next level with an API documentation tool, like SwaggerHub. SwaggerHub takes care of all the infrastructural considerations and security implementation out of the picture, allowing organizations to seamlessly collaborate and create great API documentation that consumers and development teams will love. Learn more about documenting APIs with SwaggerHub. Or try SwaggerHub for free today.