The technology industry has been putting its weight behind microservices as the way to design, build, and deploy business functionality. To help companies leverage the full benefit of a microservices architecture, rapid and agile development processes like Scrum and Kanban are becoming mainstream.
While these processes reduce time to market and increase productivity, they also create a challenge related to documentation. Traditional methodologies like Waterfall placed a large emphasis on documentation. However, when Agile-based methodologies came along, they tended to skew heavily in the opposite direction. They prioritize the production of code above all else. Indeed, this idea is so central to the Agile philosophy that it featured in the seminal “Agile Manifesto,” which prioritized “working software over comprehensive documentation.”
While the Agile philosophy’s de-emphasis on documentation might be useful for helping to get software out the door faster, in the real world, you need good documentation in addition to good code if you want anyone to use your software. That’s why modern developers need to find ways to write documentation quickly and efficiently, even if they embrace Agile methodologies.
That is where frameworks like OpenAPI and RAML come in with their supporting toolsets including Swagger and Stoplight. In this article, we take a look at how the leading option of using Swagger to implement OpenAPI can be useful for helping developers write documentation for APIs, one of the core elements of modern applications.
The Evolution of API Specifications
In the 1990s and 2000s under the SOA model, services were built using WSDL as the standard for describing the payload that passed over the SOAP transportation layer. (SOAP is XML over HTTP.) WSDLs have very little flexibility built into the standard, which makes them easier to integrate with new third-party systems, but not very readable by humans.
Microservices use an interface pattern that was built to be the other extreme from the SOAP-WSDL standard and allows for nearly unlimited flexibility. The new transport layer is called RESTful and is either XML, YAML, or JSON over HTTP. The most common language in use, by far, is JSON.
API Documentation
As more development teams started rolling out microservices using a RESTful interface, they discovered a need for an easier way to communicate their specifications and provide some kind of documentation around the API for their microservice. There have been multiple competing standards in this area, but by far the leading option for documenting APIs is OpenAPI (formerly Swagger).
Using the affiliated Swagger UI framework in addition to the base OpenAPI framework will provide a web page with a central landing page to download the documentation and also offer a method to visually see and interact with all the functions and their parameters. There are alternatives to Swagger UI; they range from open source solutions like ReDoc,/a> to commercial services like readme, which can generate a more polished and refined version of the documentation.
The OpenAPI Initiative has examples of documented APIs using version 2.0 and 3.0 of their specification in a project on GitHub.
The most comprehensive live example of a UI generated by Swagger UI is the Petstore.
As you can see, the API documented with a nicely generated web page will allow other development teams to easily start interacting with your API without needing your support.
How Does OpenAPI Documentation Help Improve Productivity?
A single reference that is version-controlled to track changes over time to your API will provide valuable as time progresses.
Another huge benefit is that all of the top API monitoring and test suites can import OpenAPI specifications to automatically populate a basic set of test cases that will test all the function points in the API. In addition, OpenAPI tools can prove valuable if you decide to use an external API management suite like one from Azure or AWS. In that case, you can simply run Import and all the endpoints have been created and validated.
The last major benefit may not help the team developing the API, as they already have code created to support it, but with an OpenAPI specification, you can use the Swagger CodeGen tool. CodeGen can be used to generate API client code in over 20 languages including PHP, Java, Python, C#, and Swift. A full list and more information is available in CodeGen’s GitHub repository.
Creating a OpenAPI Specification
The essentials of a specification are the version of the framework (called swagger in v2.0 and openapi in v3.0), an info section that details things like the API name and version, a servers section that lists the URLs used to access the service, a paths section that contains all the details about the specific functions available, and finally a components section that can be used to define things like data objects used.
Simple OpenAPI Specification in YAML
swagger: "2.0"
info:
title: Area Code to State/Province
description: Simply returns where the area code is assigned.
version: 0.9.9
contact:
name: Janu
url: http://www.example.com/
email: [email protected]
paths:
/{areaCode}:
get:
description: What area code to search
parameters:
- name: areaCode
in: path
required: true
description: What area code to lookup
type: string
responses:
200:
description: Successful response
This API has an input method, which uses GET and returns an object with two values: The area code that was submitted and the location it is in.
Summary
Writing API documentation may be unglamorous, but it’s essential if you want external development teams to be able to integrate and connect to your API on a self-service basis, as well as import any updated specifications into your monitoring and test suites to automatically update test cases. OpenAPI can make the API documentation process easier than you think.
