Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

API Documentation Beyond the Basic Swagger UI

DZone's Guide to

API Documentation Beyond the Basic Swagger UI

You can go beyond a basic Swagger integration and add serious additional value to your API's documentation. Read on to find out what you might be missing!

· Integration Zone
Free Resource

Share, secure, distribute, control, and monetize your APIs with the platform built with performance, time-to-value, and growth in mind. Free 90-day trial of 3Scale by Red Hat

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 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.

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.

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 one 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 code generator.

Explore the core elements of owning an API strategy and best practices for effective API programs. Download the API Owner's Manual, brought to you by 3Scale by Red Hat

Topics:
teams ,documentation ,swagger ,ui ,api ,swaggerhub

Published at DZone with permission of Ryan Pinkham, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}