With the use of APIs on the rise, developer usability is a focal point for many platform architects. But creating a self-service developer portal is no easy task, and the true champions provide support that directly matches the needs of their developers.
The OpenAPI Specification (OAS) has become the de facto way to define web APIs. Using the specification, many open-source tools now exist to generate helpful resources to improve your dev portals, such as documentation, SDKs, code samples, guides, interactive sandboxes, and more.
When clients and servers communicate using REST APIs, an OpenAPI Specification acts as a contract, spelling out the possible methods and metadata associated with the API. It’s a nice machine- and human-readable source of truth.
In addition to acting as a contract, developers can use OAS files—typically either a YAML or JSON file containing the areas Info, Servers, Security, Paths, Tags, ExternalDocs, and Components—to create reference documentation, set up mock servers and prototype APIs, create libraries, and more, making it a powerful component of an API design strategy.
Here are eight open-source packages you can use to generate developer resources from the OpenAPI Spec, gauge the viability of auto-generation, and complement the overall API experience.
1. OpenAPI generator
API client generation with impressive community support
This comprehensive client generator is one of the most community-supported open-source libraries for leveraging an OAS file. With support for OAS v2.0 and v3.0, the package generates client libraries (SDKs) for over 40 different languages and server stubs for a good portion as well. It can generate HTML documentation too. OpenAPI Generator was forked from Swagger Codegen in an effort to solve certain issues.
This code will generate a PHP client for the sample Petstore YAML file:
git clone https://github.com/openapitools/openapi-generator
cd openapi-generator
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
-g php \
-o /var/tmp/php_api_client
2. ReDoc
Documentation generator
The React-based Redoc package will generate simple two-columned documentation given an OAS file. The sleek Redoc reference docs include a simple three-panel style, interactive dropdown for nested objects, a CLI, and OAS v3.0 support. There is also code sample support (with a vendor extension). At time of writing, an API console was on the development roadmap. Sample documentation exists for Google Calendar, Docker Engine, Rebilly, and others.
This sample deployment demonstrates an HTML insert to embed such docs:
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
3. Swagger Codegen
Generate all types of API client libraries
As the documentation describes, “the Swagger Codegen is an open-source code-generator to build server stubs and client SDKs directly from a Swagger defined RESTful API.” It similarly parses an OAS file to quickly prototype clients and sample code for REST APIs. A benefit of adopting Swagger Codegen, as opposed to OpenAPI Generator, could be the active support from Smartbear, the progenitor of the Swagger specification. For more information, see the GitHub or Docker image.
4. LucyBot DocGen
Quickly generate a static developer reference center
The open-source iteration of LucyBot doc gen includes a documentation and API testing console, custom domain, and custom theme. To initiate it, simply clone this repository using a link to your own OAS file. A major downside is that the license is restricted to noncommercial use.
git clone https://github.com/LucyBot-Inc/documentation-starter
cp /path/to/my/openapi.json documentation-starter/openapi.json
5. API Transformer
Easily convert between API description formats
API Transformer accepts 16 various API specification types as inputs, (API Blueprint, Swagger 1.0, 2.0, WSDL, RAML, and more) and can output descriptions in the format of your choice. You simply upload your API description file (or select a destination URL), choose a target format, and hit convert. With API Transformer, users of other description formats such as RAML, for example, could reap the benefits of OpenAPI. Though technically not open source, API Transformer is free to use here.
6. DapperDox
Docs and API explorers for many services
DapperDox is an open-source package for generating browsable reference documentation and API explorers given an OAS file. With the ability to document multiple specs, it could be used to cross-reference a suite of various microservice products. Other features include API key generation and management and custom themes, making it an impressive feature set for an open-source package. Learn more on GitHub.
7. Widdershins
Documentation generation in the Slate style
Widdershins, meaning “anticlockwise,” helps produce three-columned static documentation, including a column for navigation, one for HTTP methods, parameters, and responses, as well as code samples for JavaScript, Ruby, Python, Java, and more. Slate is the popular API documentation style used by NASA, Sony, Best Buy, and many others. In addition to OAS, Widdershins also accepts AsyncAPI 1.x and Semoasa 0.1.0 API definitions.
Here is some example command-line usage:
node widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --summary defs/petstore3.json -o petstore3.md
8. API Spec Converter
Convert between API formats
This API spec converter developed by LucyBot will take an OpenAPI file and transform it into the API definition format of choice. Designed to help REST API developers avoid vendor lock-in, it aids support for tools that support only particular formats. It should be noted that OAS v3.0 is only supported using the command-line tool at the time of writing.
OAS is maturing, delivering helpful OSS
Originated from Swagger, OAS is a growing standard. Member count at the OpenAPI Initiative (OAI) stands at around 30, with the likes of Google, IBM, PayPal, and others as members. It’s three years old and at v3.0, meaning it’s fresh, yet has had time to resonate with many developers, grow, and spawn a community of support tools.
Auto-generation for third-party developer-facing resources, such as docs and libraries, is one key feature. However, there are many more tools compatible with OAS for more operational and internal needs, such as testing, validation, parsing, GUI editors, specification generators, and more.
How to generate developer resources with OAS
APIs, packaged as internal microservices or SaaS, are a common offering in the digital marketplace. To stand out, fine-tuning the developer onboarding process is key. Managers in charge of making a product out of an API can increase usability and help appeal to a wider base by using open-source tooling to generate helpful reference material.
Of course, these packages rely on you using OAS as the single source of truth. While open-source auto-gen tools are great for quick prototyping, your long-term solutions will likely evolve over time into more sophisticated iterations. Regardless, the availability of such free solutions demonstrates a thriving community and prove how using OAS as a single source of truth comes with major benefits.
Keep learning
Take a deep dive into the state of quality with TechBeacon's Guide. Plus: Download the free World Quality Report 2022-23.
Put performance engineering into practice with these top 10 performance engineering techniques that work.
Find to tools you need with TechBeacon's Buyer's Guide for Selecting Software Test Automation Tools.
Discover best practices for reducing software defects with TechBeacon's Guide.
- Take your testing career to the next level. TechBeacon's Careers Topic Center provides expert advice to prepare you for your next move.
