Skip to content

A code generator for OpenAPI written in node and designed to have pluggable generators

License

Notifications You must be signed in to change notification settings

karlvr/openapi-generator-plus

Repository files navigation

OpenAPI Generator Plus

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

Quick start

To create a new project to generate an API client or server in the current working directory:

npm init openapi-generator-plus

The script searches for the latest generator templates available on npmjs.com.

You must first choose the type of API library you want to generate:

Image of choosing a generator type

You will then be prompted to choose from a list of appropriate generator templates:

Image of choosing a generator template

The script will create a package.json and config.yml, install OpenAPI Generator Plus and the generator template, and setup a build script.

Image of complete installation

Edit the config.yml to point to your API specification, and where you'd like to output the generated API.

Image of editing config

Then generate your API.

npm run generate

Re-run that command any time your API specification changes, or you update OpenAPI Generator Plus.

See create-openapi-generator-plus for more options.

Updating

New versions of OpenAPI Generator Plus and generator templates are released from time to time. Updating to the latest version is the same as updating dependencies in any Node.js project.

We recommend updating using npm-check-updates by running these commands in the generator project directory:

npx npm-check-updates -u
npm install

Then regenerate:

npm run generate

Using

You can specify basic options on the command-line:

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

You can also use a config file, which contains more advanced options to control the generated output:

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

Generator template

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

You can find generator templates 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

Using a generator template

Each generator template 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.

Option Description
-c <path> The path to a configuration file to load (see below)
-o <path> The path to the output directory.
-g <module or path> The module name of or path to a generator template.
<path> The path to the input API specification.

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

Configuration

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

Property Type Description Default
inputPath string The path to the input API specification, relative to the config file. undefined
outputPath string The path to the output directory, relative to the config file. undefined
generator string The name of the generator template, or the path relative to the config file for the generator template module. undefined
options Options Additional options to control the generation. undefined

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

Options

Property Type Description Default
operations Operations Options specific to generation of operations undefined

Operations

Property Type Description Default
defaultRequestBodyIdentifier string The identifier to use for the request body (OpenAPI 3) "request"
groupBy "path" | "tag" | "default" The strategy for grouping operations. The default is to use tags, if present on an operation and to fallback to paths. If a specific strategy is specified, only that strategy will be used. "default"

Background

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

OpenAPI Generator Plus is written in TypeScript and uses Node.js. It 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 for the community to use and to be involved.

Operation grouping

API operations are grouped by the generator template. 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 Plus supports the following vendor extensions:

Extension Context Description
x-group Operation Override the operation group name.
x-no-client Operation, Schema Don't output when generating client code.
x-no-server Operation, Schema Don't output when generating server code.
x-schema-name Schema Override the name of the generated code for a schema.
x-discriminator-mapping Schema, oneOf, anyOf Specify discriminator mappings in OpenAPI v2

About

A code generator for OpenAPI written in node and designed to have pluggable generators

Resources

License

Stars

Watchers

Forks

Packages

No packages published