You are here

8 open source tools that will lift your API game

public://pictures/billd.jpg
Bill Doerrfeld, Consultant, Doerrfeld.io

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.

A Developer's Guide to the OWASP Top 10

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

[ Conference: DevDay: The what, how, and where of modernization (Jan 29+) ]

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.