Use your API OpenAPI 3 definition to generate code, documentation, and literally anything you need.
npm install openapi3-generator
Use your API OpenAPI 3 definition to generate code, documentation, and literally anything you need.
To use it from the CLI:
``bash`
npm install -g openapi3-generator
* Node.js v7.6+
`bash
Usage: og [options]
Options:
-V, --version output the version number
-o, --output
-t, --templates
-b, --basedir
-h, --help output usage information
`
#### Examples
The shortest possible syntax:
`bash`
og openapi.yaml markdown
Specify where to put the generated code:
`bash`
og -o ./my-docs openapi.yaml markdown
The files in your template can be of the following types:
1. Static: This kind of files will be simply copied to the output directory.
2. Templates: This kind of files will be compiled using Handlebars, and copied to the output directory.
3. Path templates: This kind of files will be compiled using Handlebars, but it will generate one file per OpenAPI path.
Assuming we have the following OpenAPI Spec:
`yaml`
openapi: "3.0.0"
info:
version: 1.0.0
title: OpenAPI Petstore
license:
name: MIT
servers:
- url: http://petstore.openapi.io/v1
paths:
/pet:
get:...
post:...
/pet/{petId}:
get:...
/user/login:
post:...
/user/{username}:
get:...
put:...
delete:...
...
And some template files like this:
|- index.js // This file contains static code, e.g. starting a webserver and including ./api/index.js
|+ api/
|- index.js.hbs // This is a static template, it contains placeholders that will be filled in, e.g. includes for each file in routes
|+ routes/
|- $$path$$.route.js.hbs // This file will be generated for each operation and contains skeleton code for each method for an operation.
|+ $$path$$/ // This folder will also be generated for each operation.
|- route.js.hbs // This is another example of an operation file.
The first important thing to notice here is the variable notation in . It will be replaced by the name of the path.
This example also shows $$path$$ used in a folder name - the generated folder names here will replace $$path$$ with
the name of the path (in kebab-case).
In this example the generated directory structure will be like this:
`
|- index.js // This file still contains static code like before.
|+ api/
|- index.js // This file will now e.g. have included the two files in routes.
|+ routes/
|- pet.route.js // This file contains the code for methods on pets.
| // (e.g. getPet, postPet, getPetByPetId).
|- user.route.js // This file will contain the code for methods on users.
| // (e.g. postUserLogin, getUserByUsername, putUserByUsername, deleteUserByUsername).
|+ pet/
| - route.js // this file also contains the code for methods on pets.
|+ user/
| - route.js // this file also contains the code for methods on users.
extensions, which will be removed when writing the generated
file. e.g. index.js.hbs writes index.js. index.js would also write to index.js, if you prefer to omit the hbs
extension.The only case where the
.hbs extension isn't optional would be if you are writing handlebars templates with the
templates. In that case the the template would need the extension .hbs.hbs. usertpl.hbs.hbs writes usertpl.hbs
(but as a source would write usertpl with no extension).$3
The generator passes the OpenAPI spec to template files, so all information should be available there.
In addition to that, the code generator adds a bit more data that can be helpful.#### Examples:
##### Dynamically require files in JavaScript
`mustache
{{#each @root.openapi.endpoints}}
const {{.}} = require('./routes/{{.}}.route.js')
{{/each}}
`
will produce (using the OAS Spec example from above):
js
const pet = require('./routes/pet.route.js')
const user = require('./routes/user.route.js')
`$3
| Param | Type | Description |
| --- | --- | --- |
|openapi|object|The OpenAPI spec.|
|openapi.endpoints| object | All first level endpoints (e.g and user) |$3
If your template needs Handlebars helpers, you can define them in a directory called .helpers inside your template.Check out some examples in the markdown template.
$3
If you want to use partials in your template, define them in a directory called .partials inside your template.Check out some examples in the markdown template.
> The name of the partial will be obtained from the file name, converted to camel case. So, for instance, if the file name is
my-partial.js, you can use the partial with {{> myPartial}}`.* Fran Méndez (@fmvilas)
* Richard Klose (@richardklose)