oas-mustache-generator

The OpenAPI Generator that is used widely is Java based. This project intends to:

• provide that functionality in pure NodeJS and continues to use Mustache templates
• add interactivity in the CLI using Inquirer.js
• add modules for generating stuff at https://github.com/gothinkster/realworld that is missing in the Java counterpart by using the code there as base
• add a folder structure for better navigation
• allow use of symlinks for reuse of templates with file override functionality
• provide a test bed for both unit and integration testing by utilising Facebook's Jest testing framework

Getting Started

Pre-requisites

• Install Node JS
• download oas-repo and build or use npm
• download this source code or use npm

Installation

npm install oas-mustache-generator --save-dev

Usage

npm start [modelFileName]

Tests

Run the tests by npm test

Contributing

All contributions are welcomed for:

• Porting the existing mustache templates from https://github.com/OpenAPITools/openapi-generator and creating the JS mapper/handlers
• Adding templates and mappers/handlers for new modules
• Enhancing the core parts
• Improving the documentation

ToDos

• Complete the modules for
  • react-redux
  • aws-dynamodb-lambda: No scan operation only Query. Multi and Single table flavors
    • using serverless framework
    • using SAM framework
    • using Claudia.js
• Modify/Refactor the template and tests to accommodate the following
  • RSQL/FIQL query's param parsing
  • Clearer REST Schema to DB Schema mapping

Patterns and Heuristics for DB binding

This also provides an opiniated framework for using OpenAPI to define DB functionality. The following patterns have been used:

• All APIs with an id for read automatically suggests that the id is a unique primary key
  • This id may be provided in Create
  • If not provided assumed to be auto-generated
• The attributes of format date-time for all Schema that do not appear in their Create or Update are assumed to take the activity time stamp
  • such property starting with create is considered immutable and others are update with updation time
• Request and response with an attribute same as the model name is considered enveloped
• limit, offset, sortBy etc. are considered reserved words for queries. Anything starting with _ is also not viewed as model attribute
• Default value for sortBy is used for DB level sorting. Specified value is used at App layer. If App Layer sort option is not to be provided, can use x-db-indices for ascending sort
• Any model that has a read API is considered to be a Reference while that without the API is considered Embedded

Vendor Extensions

Some of the features required adding vendor extensions (x-...) as OpenAPI is yet to support those features or the current support is too verbose/complicated. The following extensions are used:

• x-model: Optional. Used when the App layer model name is different than the schema name. If the name is same as another schema name, then merge the two in app layer
• x-use-db-property: Indicates which DB property to use for the given schema property or query param
• x-param-constraints: This is to provide a solution for this issue https://github.com/OAI/OpenAPI-Specification/issues/256 till it gets resolved. Takes array of items. OneOf supported as such item.
• x-user-param-query: Used to get extra info from user token and add to query
• x-immutable: boolean flag to indicate that once set the attribute cannot be changed /updated. Primary keys are immutable by default
• x-db-indices: Used for defining DB level indexing

License

MIT

Credits

Inspired from the work done by people at

• https://github.com/OpenAPITools/openapi-generator
• https://github.com/gothinkster/realworld