npm install swagger-js-codegenIt is possible now to generate multiple controllers for Node.
Each controller will have a class that has several methods inside of it.
Each method represents an API, and has a default built-in response.
Definitions are generated as well.
How it works:
Definitions are generated before the APIs. File expose.js generates all of the necessary definitions and places them in the destination directory.
APIs are generated after that, based on the Mustache templates.
Module utilizes the custom Mustache templates (multi-class and multi-method).
Mustache generates a single file with a single ES5 class, that contains all of the methods.
File splitter.js splits the single file into several files with classes (based on tags in the original JSON). After the split is completed and methods are combined, they are saved as a controller file in the destination directory.
Options:
className [REQUIRED]: name of the single generated class. You can put any name.
swagger [REQUIRED]: loaded Swagger JSON file.
multiple [REQUIRED]: this option should be provided and should be set to true if you need a multi-class output.
path [REQUIRED]: location of the destination directories. __dirname is the best option, but you can provide your own destination path.
controllersDirName [OPTIONAL]: this is the name of the destination directory for controllers. routes_generated is the recommended name (it is used as default if this option was not provided).
definitionsDirName [OPTIONAL]: this is the name of the destination directory for definitions. definitions_generated is the recommended name (it is used as default if this option was not provided).
Multi-class generation example:
const { CodeGen } = require('swagger-js-codegen');
const fs = require('fs');
const file = 'swagger/swagger.json';
const spec = JSON.parse(fs.readFileSync(file, 'UTF-8'));
await CodeGen.getNodeCode({
className: 'Service',
swagger: spec,
multiple: true,
path: __dirname,
controllersDirName: 'routes_generated',
definitionsDirName: 'definitions_generated',
});
var fs = require('fs');
var CodeGen = require('swagger-js-codegen').CodeGen;
var file = 'swagger/spec.json';
var swagger = JSON.parse(fs.readFileSync(file, 'UTF-8'));
var nodejsSourceCode = CodeGen.getNodeCode({ className: 'Test', swagger: swagger });
var angularjsSourceCode = CodeGen.getAngularCode({ className: 'Test', swagger: swagger });
var reactjsSourceCode = CodeGen.getReactCode({ className: 'Test', swagger: swagger });
var tsSourceCode = CodeGen.getTypescriptCode({ className: 'Test', swagger: swagger, imports: ['../../typings/tsd.d.ts'] });
console.log(nodejsSourceCode);
console.log(angularjsSourceCode);
console.log(reactjsSourceCode);
console.log(tsSourceCode);var source = CodeGen.getCustomCode({
moduleName: 'Test',
className: 'Test',
swagger: swaggerSpec,
template: {
class: fs.readFileSync('my-class.mustache', 'utf-8'),
method: fs.readFileSync('my-method.mustache', 'utf-8'),
type: fs.readFileSync('my-type.mustache', 'utf-8')
}
});In addition to the common options listed below, getCustomCode() requires a template field:
template: { class: "...", method: "..." }
getAngularCode(), getNodeCode(), and getCustomCode() each support the following options:
moduleName:
type: string
description: Your AngularJS module name
className:
type: string
lint:
type: boolean
description: whether or not to run jslint on the generated code
esnext:
type: boolean
description: passed through to jslint
beautify:
type: boolean
description: whether or not to beautify the generated code
mustache:
type: object
description: See the 'Custom Mustache Variables' section below
imports:
type: array
description: Typescript definition files to be imported.
swagger:
type: object
required: true
description: swagger objectThe following data are passed to the mustache templates:
isNode:
type: boolean
isES6:
type: boolean
description:
type: string
description: Provided by your options field: 'swagger.info.description'
isSecure:
type: boolean
description: false unless 'swagger.securityDefinitions' is defined
moduleName:
type: string
description: Your AngularJS module name - provided by your options field
className:
type: string
description: Provided by your options field
domain:
type: string
description: If all options defined: swagger.schemes[0] + '://' + swagger.host + swagger.basePath
methods:
type: array
items:
type: object
properties:
path:
type: string
className:
type: string
description: Provided by your options field
methodName:
type: string
description: Generated from the HTTP method and path elements or 'x-swagger-js-method-name' field
method:
type: string
description: 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'COPY', 'HEAD', 'OPTIONS', 'LINK', 'UNLIK', 'PURGE', 'LOCK', 'UNLOCK', 'PROPFIND'
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
- COPY
- HEAD
- OPTIONS
- LINK
- UNLIK
- PURGE
- LOCK
- UNLOCK
- PROPFIND
isGET:
type: string
description: true if method === 'GET'
summary:
type: string
description: Provided by the 'description' or 'summary' field in the schema
externalDocs:
type: object
properties:
url:
type: string
description: The URL for the target documentation. Value MUST be in the format of a URL.
required: true
description:
type: string
description: A short description of the target documentation. GitHub-Markdown syntax can be used for rich text representation.
isSecure:
type: boolean
description: true if the 'security' is defined for the method in the schema
parameters:
type: array
description: Includes all of the properties defined for the parameter in the schema plus:
items:
camelCaseName:
type: string
isSingleton:
type: boolean
description: true if there was only one 'enum' defined for the parameter
singleton:
type: string
description: the one and only 'enum' defined for the parameter (if there is only one)
isBodyParameter:
type: boolean
isPathParameter:
type: boolean
isQueryParameter:
type: boolean
isPatternType:
type: boolean
description: true if *in* is 'query', and 'pattern' is defined
isHeaderParameter:
type: boolean
isFormParameter:
type: booleanYou can also pass in your own variables for the mustache templates by adding a mustache object:
var source = CodeGen.getCustomCode({
...
mustache: {
foo: 'bar',
app_build_id: env.BUILD_ID,
app_version: pkg.version
}
});Some proxies and application servers inject HTTP headers into the requests. Server-side code may use these fields, but they are not required in the client API.
eg: https://cloud.google.com/appengine/docs/go/requests#Go_Request_headers
/locations:
get:
parameters:
- name: X-AppEngine-Country
in: header
x-proxy-header: true
type: string
description: Provided by AppEngine eg - US, AU, GB
- name: country
in: query
type: string
description: |
2 character country code.
If not specified, will default to the country provided in the X-AppEngine-Country header
...There is a grunt task that enables you to integrate the code generation in your development pipeline. This is extremely convenient if your application is using APIs which are documented/specified in the swagger format.
28.io is using this project to generate their nodejs and angularjs language bindings.