Skip to content

Latest commit

 

History

History
276 lines (234 loc) · 8.6 KB

README.md

File metadata and controls

276 lines (234 loc) · 8.6 KB

Swagger to JS & Typescript Codegen

Installation

npm install swagger-js-codegen

Multi-class generation (Node)

It 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',
});

Example

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);

Custom template

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')
    }
});

Options

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 object

Template Variables

The 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: boolean

Custom Mustache Variables

You 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
    }
});

Swagger Extensions

x-proxy-header

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
      ...

Grunt task

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.

Who is using it?

28.io is using this project to generate their nodejs and angularjs language bindings.