Due to changes in the priorities, this project is currently not being supported. The project is archived as of 9/17/21 and will be available in a read-only state. Please note, since archival, the project is not maintained or reviewed.

oas-nodegen

A library for generating completely customizable code from the Open API Specification (FKA Swagger) RESTful API documentation using the scripting power of Node.js.

Installation

Install oas-nodegen through npm

$ npm install oas-nodegen

Overview

This library is used to compose scripts that produce customizable output using the simple components depicted below. Most of the customization occurs in the various callbacks that the library exposes. Phase callbacks are used to modify the specification data prior to being sent to templates. The Write callbacks are used to route processed portions of the specification to their target template and location in the filesystem.

Features:

• 100% scriptable and customizable code generation.
• Loader handles loading the API specification as well as any referenced external specification.
• Modules registers and loads out of the box or custom code generation modules.
• Templates registers new template engines and compiles template source into functions.
  • The included engines are:
    • Handlebars.js
    • Hogan.js
    • Jade / Pug
    • Underscore.js
  • Template files can be overridden by adding a template directory with overlapping template file names.
• Generator takes a "composition over inheritance" approach that allows you to register any number of modules for model decoration.
• Writer handles cleaning the target directory, recursively creating directories, and writing files with content that is usually generated by templates.

Usage

Require the module before using

var nodgen = require('oas-nodegen');

var loader = nodegen.createLoader();
var modules = nodegen.createModules();
var templates = nodegen.createTemplates();
var writer = nodegen.createWriter(baseDir);
var generator = nodegen.createGenerator(config);
var utils = nodegen.Utilities;

Roadmap

Currently, this library contains several modules for generating Java-based producers and consumers. We'll likely add modules for other popular and emerging languages (e.g. Scala and Golang). That doesn't stop you from creating a module for your favorite language or framework now! The Java module is a good starting point for understanding the handling type translation and language features such as annotations, etc. If you think it would help the community, please contribute it back!

API

Loader

View the JSDoc

• load( pathOrUri ).then( function onSuccess ).fail( function onFailure );

Modules

View the JSDoc

• registerLibrary( library );
• registerModuleDirectory( [ path ] );
• registerModule( path );
• get( [ names ] );

Templates

View the JSDoc

• setDefaultOptions( defaultOptions );
• registerLibrary( library );
• registerEngineDirectory( path );
• registerEngine( pathOrObject );
• registerTemplateDirectory( path )
• compileFromSource( engineName, source, options );
• compileFromFile( templateFile, options );

Writer

View the JSDoc

• setLeadingFileComments( comments );
• setTrailingFileComments( comments );
• preventDeletionOf( pathNames... );
• clean();
• write( [ path ], filename, content );

Generator

View the JSDoc

• configure( config );
• addIgnoredOperations( operationNames );
• addIgnoredParameters( parameterNames );
• setModules( parameters );
• use( moduleNamesOrObjects );
• emit( phase, event, data );
• on( phase, event, data );
• onPrepare( event, listener );
• onDecorate( event, listener );
• onFinalize( event, listener );
• write( event, data );
• onWrite( event, listener );
• process( spec, references );
• groupOperation( operation );
• groupSort( group );
• operationSort( operation );

Utilities

View the JSDoc

• getSuccessResponse( operation );
• translate( obj, spec, references );
• resolveReference( obj, spec, references );
• getReferenceName( $ref );
• extractModelName( $ref );
• getMimeType( array );
• sortKeys( object );
• capitalize( string );
• uncapitalize( string );
• random( low, high );

Modules

The modules below are designed to enrich the API specification with information to be used by templates. The best approach is to try to keep templates as generic and simple as possible and let the addition of modules change the generated output. For example, most of the Java-based modules below deal with annotations. The provided templates simply render the list of annotations and the modules handle the heavy lifting.

Helpers

• Operations:

  • fullPath - Concatenated base path and operation path
  • accepts - Most preferred mime type for the Accepts header
  • contentType - Most preferred mime type for the ContentType header
  • operationId - If null, set based on HTTP method and path (however, its recommended to explicitly specify operationId in the specification)
  • resolvedConsumes - Resolved consumes mimetypes for this operation or base specification
  • resolvedProduces - Resolved produces mimetypes for this operation or base specification
  • Response helpers:
    • successResponse - Property that reflects the 200 or 201 response
    • hasReturn - Boolean flag that denotes of a response body is returned
  • parameters - Updates the parameters array for filter out ignored parameters
  • isQuery - Boolean flag that denotes if the query string parameters comprise are all optional (e.g. collection query)
  • Parameter grouping by type:
    • bodyParam - The body parameter, if applicable
    • pathParams - List of path parameters
    • queryParams - List of query parameters
    • headerParams - List of header parameters
    • formParams - List of form parameters
    • requiredParams - List of all required parameters

• Models:

  • name - The model name pulled from the definitions map key
  • references - The list of models that this model references
  • referencedBy - The list of models this model is referenced by
  • recursiveReferencedBy - The recursive list of models this model is referenced by
  • required - Updated with a materialized list from other entities refereced by $allOf
  • properties - Updated with a materialized map from other entities refereced by $allOf
  • vars - The model's properties represented as a list instead of a map
  • Materialized information from other models that reference this model
    • allReferences - A recursive list of models referenced by this model
    • allProperties - All properties from this model and models that reference this model
    • allRequired - All required property names from this model and models that reference this model
    • allVars - All vars from this model and models that reference this model

• Properties:

  • name - The property name pull from the properties map key
  • required - Boolean flag indicated if the property is required - pulled from the model's required list

Java

• General:
  • annotations:
    • List of annotations for operations, parameters, models, and properties
    • Added by generator.addAnnotation(annotation, operation|parameter|model|property);
  • imports
    • List of imports for resources and models
    • Added by generator.addImport(className, resource|model);
    • Generator utility methods:
      • addKnownImports(imports...) - Adds a known import that can be added via a simple class name
      • findImport(simpleName) - Finds an import using its simple name
  • classname - Java-friendly class name for resources and models
  • Type translation methods:
    • translateType(schema, resource|model, spec, references) - Converts a schema into a Java type
    • addTypeTranslator(function(schema, resource|model)) - Adds a hook used by translateType to allow for custom types
    • overrideModelPackage($ref, model) - Hook method that can be replaced in order to override model package name (returning null defaults to config.modelPackage)
    • variableName(value) - Produces a Java-friendly variable name from a string value
  • Other utility / helper methods:
    • escapeJavaString(value) - Converts a value into a Java string literal
    • joinStrings(values) - Escapes and joins a set of values - useful for declaring arrays
• Operations:
  • methodName - Java-friendle method name
  • returnType - The class name of the return type
  • returnDescription - The description from the success response
• Parameters:
  • varname - Java-friendly variable name
  • dataType - The data type of the parameter - can be a generic collection
  • itemType - The item type if the data type is a collection
  • method - The method to use to set the parameter from a client's perspective
• Models:
  • allImports - Materialized list of imports from the model and property scopes
  • parent - The class name of the parent which is based on the first reference under $allOf
  • serialVersionUID - The long value to use for serialVersionUID for implementing Serializable
• Properties:
  • varname - Java-friendly variable name
  • dataType - The data type of the property - can be a generic collection
  • getter - The getter accessor method name
  • setter - The setter accessor method name
  • defaultValue - The property's default value expression

Java8

• Properties:
  • dataType
    • Uses java.util.Optional* types when fields are not required
    • Replaces Integer, Long, and Double with OptionalInt, OptionalLong, and OptionalDouble respectively
    • Wraps other classes with Optional<T>
  • empty - The expression to create an empty optional instance
  • assign - The expression to convert and assign a value to an optional instance

JavaBeanValidation

• Parameters & Properties:
  • Adds @Min/DecimalMin, @Max/DecimalMax, @Size, @Pattern, @Valid and @NotNull

JaxB

• Models:
  • Adds @XmlRootElement, @XmlType, @XmlAccessorType, @XmlSeeAlso
• Properties:
  • Adds @XmlElementWrapper, @XmlElement based on defined xml objects

JaxRS

• Resources:
  • Adds @Path, @Consumes, @Produces
• Operations:
  • Adds @Path, @Consumes, @Produces
  • Adds @GET, @POST, @PUT, @DELETE, @HttpMethod("PATCH")
• Parameters:
  • Adds @PathParam, @QueryParam, @HeaderParam, @FormParam, @DefaultValue

Example

To try an example, use the commands below to build and run a Java/Spring Boot API (assumes MongoDB is running and listening on 27017 - authentication disabled):

$ git clone https://github.com/capitalone/oas-nodegen-example.git
$ cd oas-nodegen-example
$ gradle bootRun

Tests

To run the test suite, first install the dependencies, then run npm test:

$ npm install
$ npm test

Contributors

We welcome your interest in Capital One’s Open Source Projects (the “Project”). Any Contributor to the project must accept and sign a CLA indicating agreement to the license terms. Except for the license granted in this CLA to Capital One and to recipients of software distributed by Capital One, you reserve all right, title, and interest in and to your contributions; this CLA does not impact your rights to use your own contributions for any other purpose.

Link to CLA

This project adheres to the Open Source Code of Conduct. By participating, you are expected to honor this code.