OpenAPI Generator+

A code generator for OpenAPI 2.0 and 3.0 written in TypeScript and Node.js, with modular language-specific generator modules.

Installing

We recommend installing OG+ locally in your project so you can control the version of the tool and any generator modules that you use.

If you don't already have a node project, create one using npm init (you can just press return for any questions you don't know the answer to).

npm install --save-dev openapi-generator-plus

Then run using:

npx openapi-generator-plus ...

Or add a run script, e.g.

"scripts": {
    "api": "openapi-generator-plus -c config.yml --clean"
}

Using

You can either specify all options on the command-line:

npx openapi-generator-plus [-c <config file>] [-o <output dir>] [-g <generator module or path>] [<path or url to api spec>]

Or you can put all or some of the options in a config file:

npx openapi-generator-plus -c <config file>

Generator modules

OpenAPI Generator+ requires a generator module in order to generate code in your target language and style.

You can find generator modules by searching for the #openapi-generator-plus-generator keyword on npm.

For example, to install a generator for a Java server using the CXF library with CDI:

npm install --save-dev @openapi-generator-plus/java-cxf-cdi-server-generator

Running

Each generator module has different configuration, which you can determine from the generator's README.

First try running without any configuration:

npm openapi-generator-plus -o build -g @openapi-generator-plus/java-cxf-cdi-server-generator api.yml

Command-line options

Options to the generation process can be specified on the command-line or in a configuration file.

Command-line options override their respective configuration options (see below).

Configuration

The configuration file may be YAML or JSON. A basic configuration file contains:

See the README for the generator module you're using for additional configuration options supported by that generator.

Background

OpenAPI Generator+ is a reimplementation of code generation for OpenAPI specifications, following in the footsteps of swagger-codegen and openapi-generator.

OG+ is written in TypeScript and uses Node.js. OG+ aims to provide a strong core to transform API specifications for code generation, and to rely on separate code generation modules for the final code generation step. This separation enables the templates and minimal code required for each new language to be developed, packaged and published independently, making customisation more powerful and easily accessible.

Templates

OG+ has an incompatible object model and approach to other Swagger / OpenAPI code generators so templates must be rewritten or modified in order to be used with OGN. This is usually not a complicated process as the properties available to templates are well-defined by TypeScript interfaces.

Handlebars

OG+ uses Handlebars for templating. Handlebars builds on the functionality of the mustache templates used in swagger-codegen making templates more powerful and easy to customise. Handlebars also supports custom helpers to put more capability into templates, such as case transformations.

Operation grouping

API operations are grouped by the generator module. The usual mode of operation is to work out the name of the group by:

1. A vendor extension x-group on the operation or path.
2. The first tag on the operation.
3. The first path component.

Vendor extensions

OpenAPI Generator+ supports the following vendor extensions:

Building

See OpenAPI Generator+ for more information.