3 Tools to Auto-Generate Client Libraries From OAS

For companies and developers who distribute apps and bundled APIs, providing client libraries has become nearly essential. An API — public or private — isn’t handy if users struggle to utilize it. Accordingly, these libraries supply code that promotes API usage and jumpstarts projects. As we’ve previously highlighted, client libraries are a core element of the overall developer experience. To summarize some key points, API client libraries do the following:

  • Accelerate development and API integration.
  • Provide codification of API processes per specific programming languages.
  • Provide automatic formatting of data types to fit specific scenarios.
  • Reduce the probability of errors occurring during usage.

Third-party tooling is the key to making this happen. For some time, the OpenAPI Generator has been front and center in most developers’ minds. However, those seeking alternatives have options in the marketplace. Are you looking to auto-generate client libraries for your own APIs? We’ve rounded up some notable tools that could make your development life much easier.

REST API Client Code Generator

Found within the Visual Studio Marketplace, Christian Resma Helle’s client generator aligns well with OpenAPI and Swagger specification files. Chiefly, it allows for client library creation and client generation using tools like AutoRest, NSwag, Swagger Codegen, and the OpenAPI Generator. The tool also does the heavy lifting with updates —automatically pushing code changes to generated files, when existing YAML or JSON files change.

The Client Code Generator includes a collection of code generation capabilities for the C# language; it works seamlessly with Visual Studio, a stalwart in the IDE realm. It’s something of a compilation tool, blending multiple library generator functionalities into one all-encompassing piece of software.

Additionally, the REST API Client Code Generator bundles these four primary tools:

  • AutoRestCodeGenerator: Creates a single file REST API client in C# via AutoRest, mirroring what’s possible via the AutoRest CLI tool.
  • NSwagCodeGenerator: Leverages the NSwag.CodeGeneration.CSharp NuGet package to create a single file C# REST API client.
  • SwaggerCodeGenerator: Accomplishes the above via the Swagger Codegen CLI v3.0.14. The resulting file arises from merging all files generated using the Swagger Codegen CLI.
  • OpenapiCodeGenerator: Accomplishes the above via the OpenAPI Generator v5.10, also as a result of file merges.

Note that some dependencies are necessary to use this tool. Depending on your preferred tool or language, it may be necessary to install NPM and the Java Runtime Environment. Alternate Java SDK implementations mesh well here. RestSharp, Jsonsubtypes, Newtonsoft.Json, or Microsoft.Rest.Client.Runtime are required to run specific custom tools within. The tool makes some assumptions, but the Settings menu lets you dive in and configure as needed to extract more from Client Code Generator. For example, you might dictate how NuGet packages are handled or how .nswag files are generated from various criteria.

The REST API Client Code Generator is reasonably popular on the Marketplace. It also receives top marks, albeit from a small body of reviews. If you already have experience with other tools but desire a workflow change, then this tool might be a perfect solution for you.

Azure AutoRest

Image courtesy of Esteban Villegas, via Stack Overflow.

Created by Microsoft and maintained by over 120 GitHub contributors, Azure AutoRest bills itself as an OpenAPI code generator. Mainly, the program excels at automatically generating client SDKs in numerous languages — including C#, PowerShell, Go, Java, Node.js, TypeScript, Python, and Ruby. That covers a massive swath of developers, making AutoRest one of the more agnostic tools currently available. AutoRest is also open-source, meaning you can both harness and contribute to its development. It enjoys significant backing — meaning it won’t be abandoned anytime soon.

Accessing REST services is easy from an AutoRest-generated library. The tool abides by the official OpenAPI specification format, which generally speeds development along while making the process (and the end product) highly accessible. As David Justice summarizes, AutoRest is meant to prevent developers from HAVING to handcraft various API calls and associated structures. It’s a tedious source of frustration that AutoRest counteracts. The tool can output “generic” Swagger per the specification or output more opinionated Azure Swagger libraries. The latter applies most to Microsoft’s own APIs.

AutoRest works with JSON files within Visual Studio — and any annotations are picked up via AutoRest as required. Regeneration of client code is possible via automation. The tool is excellent at creating production functionality and testing components, giving developers multiple ways to simplify their APIs for end users. It’s easy to specify namespaces, groupings, resources, and even extensions. A logically oriented group of operations quickly becomes a client library with a clear hierarchy.

Swagger Codegen

Image courtesy of Swagger.

As a direct contributor to the OpenAPI Specification, SmartBear maintains its own client library generator called Swagger Codegen. While something like OpenAPI Generator is maintained by the developer community, Swagger Codegen is backed by SmartBear — yet remains open-source. While the tool quickly generates client libraries in 40 different languages, it also integrates with SwaggerHub. This makes collaboration much easier via the tool’s cloud interface. As a bonus, it can generate server boilerplate code in over 20 different languages (if you’re into that), extending functionality even further.

Swagger Codegen promises to boost API consumption while remaining continuously up to date. The tool supports the OpenAPI Specification (OAS) 3.0 and higher, thus evolving in lockstep. Codegen is still maintained, though it’s not the most active project out there. The latest iteration, version 3.0.25, was released on March 4th, 2021; its predecessor in the 3.0 branch debuted in December 2020. You’ll want to ensure that any existing issues won’t markedly impede your workflow during client library generation.

Users need to have a Java 8+ runtime installed. Windows users must install wget as a prerequisite, or invoke a PowerShell web request to utilize Codegen. SmartBear notes that Apache Maven 3.3.3+ is required in your $PATH to get started. Project builds are possible using Homebrew or Docker. Like other library generators, you can leverage the Swagger Petstore file to create sample libraries, and really get a feel for how Codegen works. It’s easy to alter syntax and language support in Swagger Codegen. Simply tap into the jmustache engine to use mustache templates — either stock or customized to your liking. You may also customize the generator and file formats.

Want to build a library using Javascript? The external swagger-js-codegen component can generate Node and Angular source code from the OAS.