Introduction to OpenAPI Generator

In recent years, one of the most popular development paradigms is the practice of automatic generation. The idea of being able to plug in your code or documentation files into some sort of futuristic “universal translator” to create beautiful stubs, clients, and other outputs is, in many ways, the ultimate dream of many multi-platform developers. As such, solutions promising to unify codebases and deliver interoperable outputs are often seen as the “next big thing.”

Today, we’re going to look at one such offering for auto-generating documentation and other developer resources. OpenAPI Generator promises to be a tool with extreme extensibility and supported paradigms. Does it do any of this well? Let’s take a look.

What is the OpenAPI Generator?

OpenAPI Generator can auto-generate clients, servers, and documentation from OpenAPI 2.0/3.x documents. View the Github repo.

OpenAPI Generator is a tool designed to create API client libraries, server stubs, configurations, and documentation from OpenAPI 2.0 and 3.x documents. It boasts a wide range of functions and is used by a wide range of users, some of whom are also maintainers. OpenAPI Generator focuses on ease of use; it positions itself as being a tool for reducing the burden on new development and technologies through the integration and leveraging of OpenAPI documents.

Notably, OpenAPI Generator is a fork of swagger-codegen between versions 2.3.1 and 2.4.0. For this reason, much of the foundational concepts and offerings underlying OpenAPI Generator should feel quite familiar. The fork occurred for several reasons, as detailed in the OpenAPI Generator documentation. They mostly come down to simplicity in function, reduction in concurrent branch developments, and greater community ownership. This community involvement is significant and is a significant part of the OpenAPI Generator ethos.

Features

OpenAPI Generator claims a lot of features, but the one it seems to value the most is its simplicity. OpenAPI Generator supports over 50 client generators, which makes it quite extensible – this is very important, as it removes a major stepping stone towards adoption through providing ample compatibility and support. Additionally, OpenAPI Generator has a pretty robust set of customization options, allowing pretty much any project environment to take advantage. As an extension of this scalability, extensibility, and customizability bent, OpenAPI Generator also supports a wide range of schemas and configurations. It boasts both individual generators (Apache2 Configuration, MySQL, GraphQL) and more purpose-built generators based upon derivative code.

Server development tooling also exists, assuming you use one of the 40+ languages they support. Interestingly, the documentation notes that some of the server stub generators support “Inversion of Control.” This principle is an inversion of the code/instance relationship in classical development and creates a layer between your codebase and the instance it generates. Because the generated instance exists separated from the underlying code, you can update code without breaking the entire instance.

Of course, a main appeal for the generator is the fact that it generates documentation in addition to all of the server stubs and clients. This makes sense given its Swagger roots, and might seem a small addition, but documentation is incredibly important. We’ve discussed the importance of documentation several times previously, but given OpenAPI Generator’s abilities, its support for Inversion of Control, etc., it makes even more sense in this case.

Below is a sample of supported API clients, server stubs, documentation generators, and general files/content types. For a more exhaustive list, please see the GitHub for OpenAPI Generator.

OpenAPI Generator supports:

Bash, C#, C++, Clojure, Erlang, Go, Haskell, Java, Lua, Node.js, Perl, PHP, Python, Ruby, Rust, Swift, and other API clients.
Ada, F#, Kotlin, Python, NodeJS, Ruby, Rust, Scala, and other server instance codebases.
HTML, Confluence Wiki, and Asciidoc for API documentation generation.

Also read: Ultimate Guide to 30+ Documentation Solutions

Using OpenAPI Generator

To demonstrate how OpenAPI Generator might exist in a common workflow, let’s reference the Maven implementation.

Installation

To get started, simply add the Maven plugin to the “build->plugins” section of the codebase:


    org.openapitools
    openapi-generator-maven-plugin
    
    4.2.3
    
    
        
            
                generate
            
            
                ${project.basedir}/src/main/resources/api.yaml
                java
                
                   src/gen/java/main

Next, invoke the compilation function using “mvn clean compile.” From here, we can start configuring nodes in key/value pairs using the configuration/option/key/value structure:

In this structure, each configuration has both an option and a key/value pair – the option is a set value as defined through the general configuration parameter list within the Maven documentation, and the key/value pair is the specific values given to that option. As an example, let’s assume we wanted to create a model that paired Users with Locale. We could do this by stating the following configuration:


    
       User,Locale

Custom Generators

One caveat to this approach that is referenced several times in the OpenAPI Generator documentation is the fact that custom generators in this implementation do not support the classpath:/ synatx. Instead, everything needs to be explicitly stated, from the package (it must be the fully qualified package name) to the custom templates called. This means custom generators should be developed with overtly explicit addressing. As an example, OpenAPI Generator provides the following custom generator in the documentation:


    org.openapitools
    openapi-generator-maven-plugin
    ${openapi-generator-maven-plugin-version}
    
        
            
                generate
            
            
                ${project.basedir}/src/main/resources/yaml/yamlfilename.yaml
                
                com.my.package.for.GeneratorLanguage
                myTemplateDir

                ${project.build.directory}/generated-sources
                ${default.package}.handler
                ${default.package}.model
                ${default.package}.handler
            
        
    

    
        
            com.my.generator
            customgenerator
            1.0-SNAPSHOT

Using a Generator

Now that we’ve created a generator, we can install it:

Mvn clean install -f out/generators/my-codegen

And with this, we’ve used our generator – it’s really that simple.

Possible Caveats

OpenAPI Generator is very powerful, and has a wide range of supported languages and approaches. That being said, there are some caveats that should be considered when using it in the average workflow. These are not necessarily “deal breakers,” but they do add some greater context to the average use case.

The first major caveat that should be considered is that OpenAPI Generator is, essentially, still a fork of Swagger-centric tooling. Due to this, it inherits many of the weaknesses of an auto-generating solution. Auto-generation of anything saves a lot of time, but it’s only as good as what is fed into it. While this seems obvious, the side effect of such a system is that code that otherwise seems to work perfectly within its given implementation may in fact result in broken code or stubs upon generation.

This doesn’t happen with manually coded because the inconsistencies in code are often internally inconsistent – while this is not ideal, it does at least deliver a workable first draft of a project, and does not require perfection off the bat. While OpenAPI Generator is pretty flexible in this regard, it is still an automated solution, and as such, requires a perfect implementation to generate compatible code that 100% operates within expectations. While this is certainly a failure of the developer, and not of OpenAPI Generator, it does mean that the learning curve may, at times, seem steeper than if the coding workflow was done manually.

Even if your initial code is good, however, there’s the fact that OpenAPI Generator depends upon community-guided development and implementations for code generators that are not always mature. For some users, this may result in generators that produce unusable code, or code that in theory should be usable while in practice behaving unpredictably.

All of this being said, OpenAPI Generator is a good example of a generalist solution adding great value that may in certain workflows be best dealt with through a specialist solution. If a codebase uses a relatively specific and niche language or paradigm, it may be best to use a different solution (or at least keep in mind the relative immaturity of the OpenAPI Generator module in question). As a generalist solution, however, OpenAPI Generator is a wonderful tool. More specifically, OpenAPI Generator is a tool of acceleration – it’s probably not going to get you 100% where you want to go, but it’ll do 90% of the work and expose where the rest of the work should be directed.

Conclusion

Ultimately, any automated solution is going to be highly dependent on your specific use case. While OpenAPI Generator gets most scenarios close to having usable clients and servers, some people are looking for 100% perfect implementations. OpenAPI Generator can deliver perfect code on the first try, but it also is unlikely to do that repeatedly for every single language that’s thrown at it.

Accordingly, OpenAPI Generator is a wonderful solution in a generalist use case. If a more specialist use case is needed, it’s not the greatest choice in the world, but is still serviceable.

What do you think about OpenAPI Generator? What could make it better? Is it an appropriate generalist tool? Let us know in the comments below.