Long gone are days of technical writers merely annotating screenshots, writing FAQs, and serving as an afterthought to development. With the growth of RESTful APIs and microservices, documentation is more important than ever for both accelerating internal development, supporting technical sales and partner teams, and facilitating smooth external integrations. In fact, a 2013 survey by Programmable Web found that complete and accurate documentation was rated as the most important factor in evaluating an API—outranking service-level agreements, price, and even service uptime! Fortunately, as the value of technical documentation has continued to grow, so has the number of tools and services available to support documentation developers. One of the most significant advances in standardizing, improving and building API documentation has been the OpenAPI (Swagger) specification and tool sets.
What is OpenAPI?
OpenAPI is a specification for describing and formatting REST APIs. Written in YAML or JSON, OpenAPI provides a method for documenting the endpoints, operations, required/optional parameters, code samples, and virtually anything you need to communicate about your API. These documents are easily readable by people and machines, can be quickly edited, and even generated directly from the code base.
Formerly known as Swagger before being renamed as the OpenAPI Specification (OAS) in 2016, OAS quickly became the dominant structure for describing REST APIs. By mid-2017, OAS tools exceeded 100,000 downloads per day and have continued to grow. The specification is currently in its third iteration, and the first major release since its move to the OpenAPI Initiative. So, if it has been so successful, what’s the big deal about the latest release? And, more importantly, how can the Swagger spec give your audience the confidence to move forward with your APIs?
What’s in it for me?
As exciting as these developments are to read about, the most important thing is always the tangible, measurable benefit they can bring to your team, documentation, and strategy. For writers learning about OAS 3.0 for their developer docs, the following aspects stand out in contrast to not only other tools but also previous versions of OAS.
Simplified Structure
Regardless of how effective a tool could be, it’s not worth very much if it is impossible to learn, digest, and get up and running. With this in mind, OAS 3.0 features several adjustments to condense and simplify the structure for readability and ease-of-use. Let’s take a look at the YAML document for both OAS 2.0 and 3.0 to highlight some of these comparisons.
Hosts, URLs and Servers
Previously, version 2.0 allowed you to set a host, base URL and schemes to apply across your API documentation. With OAS 3.0, these fields are combined into a servers property, condensing the document while also providing support for multiple base URLs. These can then be defined later in the document to allow individual endpoints to have their own unique base URL if needed. This could be leveraged in the case of staging and production servers.
New Reusable Features
As the “docs-as-code” methodology continues to grow, it’s more important than ever that the structure for documenting APIs mirrors the subject matter itself. OAS 3.0 includes several adjustments to the existing components object to achieve this, with a particular focus on the reusability and consistency of the full document. The five new component objects in OAS 3.0 are:
- callbacks
- links
- examples
- requestBodies
- headers
Let’s take a more in-depth look at how two of these may function in your documentation.
Links
The links object provides a method to describe the relationships between paths. One valuable utility of this field could be directing the user to the next step or the purpose of a value return in the API response. For example, let’s say you have an API where the user enters in a GET request for data on a pet and receives an adoptID in the response. You could leverage the links object to describe how to use that adoptID to submit your adoption request in a subsequent POST.
links:
GetAdoptIdByPetId: # <---- arbitrary name for the link
operationId: getPet
# or
# operationRef: '#/paths/~1users~1{adoptId}/get'
parameters:
adoptID: '$response.body#/id'
description: >
The `adoptID` value returned in the response can be used as
the `adoptID` parameter in `POST /petStore/{adoptID}`to place an adoption hold on the given pet.Callbacks
In order to make APIs more dynamic and useful, webhooks and event-driven design are becoming more significant every day. By configuring the Callbacks object, the API documentation can detail additional out-of-band actions that may follow a given request. For example, if you have a client subscribing to your API for given events, they can see the URL where the callback returns data and the parameters of the request body they can expect. You can nest this object within a POST call as detailed in the OAS 3.0 example below:
callbacks:
# the name `onData` is a convenience locator
onData:
# when data is sent, it will be sent to the `callbackUrl` provided
# when making the subscription PLUS the suffix `/data`
'{$request.query.callbackUrl}/data':
post:
requestBody:
description: subscription payload
content:
application/json:
schema:
type: object
properties:
timestamp:
type: string
format: date-time
userData:
type: stringExamples
The inclusion of easy-to-digest examples is key to converting prospects to partners. With the new Example object, documentation can include rich-text syntax, internally embedded examples (including non-JSON/YAML media types), and URLs to reference external examples that may not have fit smoothly within the JSON/YAML document itself. Examples can be embedded in the model, parameter, request body and response level. If you can’t resist seeing examples of examples, check out how each of these methods is described in the object specification here.
Extended Support for Schema Object
OAS 3.0 expands on examples by supporting multiple media types driven from the schema. For example, for an operation that may contain a binary type for a ‘200’ response and a JSON type for a ‘400’ response, you can document both within the same schema and have this reflected in your document.
Likewise, schema definitions can be further filtered via allOf, anyOf, oneOf to improve API validation. These ensure that the chosen keywords successfully validate against every, at least one, or exactly one schema, respectively. Building on the pet store example above, let’s say the store has both cats and dogs and these objects have both shared and unique attributes. using these validating keywords can be used to ensure the response contains all the fields from both (allOf), all the fields from either (oneOf), or the fields from one or more (anyOf).
With all the new features and flexibility of OpenAPI 3.0, documentation developers can have even more impact on the design, development, and, ultimately, the success of their APIs.
For more information on all of the changes in OAS 3.0, check out the GitHub repository here.
Written by Cody Holden for DeveloperHub.io.
