It wasn’t so long ago that an API specification was just a thing that got generated. Write some code, add some annotations, and let your build tool create an API specification document you shared with your colleagues, community, friends, and family. Job done.
All that’s changed with the advent of design-first APIs. It’s become common practice for API designers to actively create the “best” design they can for humans and machines that consume their APIs. This can be done without writing a stitch of code, using tools like Stoplight coupled with the massively popular OpenAPI (fka Swagger) Specification.
The increasing importance of design-first APIs and use of API specification documents gives us some opportunities to optimize what we deliver to our developer communities. In the context of OpenAPI Specification, this is true for both humans and machines that we interact with.
Many API providers take advantage of the features in the OpenAPI specification that allow them to both define the API and document their design intentions. Key among these is the Description object, a free text property present in most objects including Info, Path, and Definition.
While this is a string, its value can be richer than simple text. For example, Markdown can happily be stored (CommonMark being supported by the specification). Most tools, like Stoplight and open source resources like Swagger UI and Redoc, will actively render the Markdown, providing convenient formatting for readers of the document.
For example, the description property in the Infoobject can be populated as follows (using a pipe for line continuation):
swagger: '2.0' info: title: Stoplight Blog - Example API version: 0.0.1 description: | # Example I like to make it easy for my readers so I'm using headers: * And * Some * Bullets
Providing Markdown support allows API providers a method for adding supplemental and secondary information. As an API designer, this functionality has a number of benefits:
By making use full of the Description field, you therefore have the opportunity to provide a rich, self-contained document with possibly everything a human needs to know about your API.
If you take Fielding’s REST architectural style at face value and fully implement both hypermedia and the optional code-on-demand constraint, an API specification wouldn’t be necessary for machines. Your client would be a dumb shell, drawing on the API for everything it needs to execute.
However — and for the time being at least — we need to tell our machines what our APIs look like. With an API specification, we give ourselves an advantage though, by using a means that can be digested by code generation tools so the core of an API client can be constructed automatically.
Sounds like an easy day for developers — generate a client and you’re off-and-running. However, an ugly API specification can result in an ugly API client, with a sprawling, unfamiliar code base that is hard to maintain and debug. In the context of OpenAPI, using the features of the specification that promote reuse will provide benefits for the developer as they implement an integration with your API:
Promoting simplicity and reuse through a well-structured API specification, therefore, gives developers the best chance of success in creating a clean and straightforward API client. Moreover, it adds to a great experience for developers, by making their lives easier.
Note: In OpenAPI 2.0 (fka Swagger), the majority of reusable types can be grouped under root-level properties such as parameters, responses, and definitions. In OpenAPI 3.0, these have been moved under the root-level componentssection with definitions renamed schemas.
Your API specification is a crucial document for communicating with your community. However, its capabilities deliver more than just a technical representation of your API.
It can provide a self-contained encapsulation of everything you need to convey your consumers, for humans and machines alike. By leveraging the features available — especially when using the OpenAPI Specification — you have more chance of increasing the breadth and depth of understanding in your developer community.