Skip to content

Home

Jump to bottom
Sandor edited this page Jan 7, 2018 · 12 revisions

Welcome to the gl-swagger-generator wiki!

Getting Started

Three different approaches are now available to use this generator.

CLI

To generate the api client, you need to give it 2 things:

  • The swagger json file of your api, defining all the available methods.
  • A configuration json file, specifying some options for your client generation.

A configuration file looks like this:

{
  "language": "typescript",
  "framework": "angular",
  "version": "1.5",
  "mode": "singleFile",
  "dependencies": {
  },
  "mediaTypesPriorities": {
    "application/json": 1
  },
  "ambientTypes": [
  ],
  "templateOptions": {
    "clientName": "MyAPIClient"
    "scheme": {
      "override": "https"
    },
    "generateInterface": true
  }
}

To generate your API client, just run swaggen with these options:

swaggen --outputPath ./outputpath --options ./swaggen-config.json --schema ./api-swagger.json

Gulp

npm install node-swagger-generator@beta --save-dev
npm install gulp-swagger-generator@beta --save-dev
var gulp = require("gulp"),
    path = require("path"),
    swaggerGenerator = require('gulp-swagger-generator'),


gulp.task('swagger:ts', function () {
    return gulp.src('./api-swagger.json')
        .pipe(swaggerGenerator({
            "language": "typescript",
            "framework": "angular",
            "version": "1.5",
            "mode": "singleFile",
            "dependencies": {
                
            },
            "mediaTypesPriorities": {
                "application/json": 1
            },
            "ambientTypes": [
            ],
            "templateOptions": {
                "clientName": "MyClient",
                "module": "MyModule"
            }
        }))
        .pipe(gulp.dest("./ClientDirectory"));
});

Node

node-swagger-generator is built as a node module you can directly integrate in your node based scripts or tools.

Documentation coming soon.

Features

Languages

  • CSharp : Note the generic support is currently extremely limited.
  • Typescript : Generics are not supported atm.

Known issues and limitations

  • No advanced date/time management especially in TypeScript
  • Generics are mostly not supported atm.
  • Templates: fix indentation

How it works

This generator relies on Handlebars templates. Those templates are applied to a model built from a swagger definition, some settings and a language provider.

When executed, a Generator will :

  • Load swagger document
  • Execute custom swagger visitors
  • Load the template
  • Generate the model
  • Apply template files to the model
  • Write output to a sink

A Sink is a class which in charge of writing the produced output. It should implement ISink interface. For instance, gulp-swagger-generator implements a through2 sink.

Model Generation

Generating the model is a complex task and it offers a few extensibility opportunities.

The inputs are :

  • Swagger schema
  • Options
  1. Swagger Visitors are the first step in the generation process :
    • Custom Visitors : This is an extensibility point. With swagger visitors you can perform operation such as swagger schema modification prior to any other operation.
    • ContextBuilder : This is a swagger visitor in charge of detecting definitions (both explicit and anonymous) and operations. It builds the Generation Context Model. ContextBuilder will use Definition and Operation Filters. They are the most common extensibility point used mostly by template. They can perform tasks such as camlCasing of arguments or PascalCasing of DefinitionNames :
      • Definition Filters : those filters will be applied to definitions.
      • Operation Filters : thoss filters will be applied to operations.
  2. Generation Context Visitors come next. They are in charge of finalization of the generation context model.
    • [WIP] Type Trimmer : Removes unecessary definitions replaced by either native types or imported types
    • [WIP] Generic Type Mapper : Detects and update generic types. This is executed only if selected language supports generics.
    • Type Mapper : Generation contexts provide an language agnostic abstracted type system. The type mapper is provided by a language pack and transforms abstracted type to language specific type information.
    • [WIP] Custom Visitors : This is an extensibility point.

Templates

A template is composed of

  • a mandatory template.json manifest file which provides template configuration
  • various handlebars template files (*.hbs). Files prefixed with an _ will be treated as partials.

A template.json is composed of :

  • name : full name
  • language : language details
  • dependencies : dependencies required by the template
  • filters : definition and operation filters the template require to run
  • modes : template generation mode. Some template can offer more than one generation option (single file vs multiple files output for instance). Each mode is composed of a set of entries. Each entry will be linked to a handlebars template, an inline naming template and a selector. The selector is used to query a part of the generation context. If selector matches an array in the Generation Context, the template will be applied to each item in the array.
{
  "name": "language-framework-version",
  "language": {
    "name": "language",
    "defaultExtension": ".cs"
  },
  "dependencies": {
    "Dependency.Name.1": {
      "version": "1.6.0"
    },
    "Dependency.Name.2": {
      "version": "9.0.1"
    }
  },
  "definitionFilters": [
    "arrayName",
    "pascalCaseName"
  ],
  "operationFilters": [
    "pascalCaseName",
    "camlCaseArgumentName",
    "optionalArgsOrder"
  ],
  "modes": {
    "singleFile" : {
        "entries": [ {
          "template": "singleFile.hbs",
          "naming": "{{options.clientName}}.cs",
          "selector": ""
        }]
    },
    "project": {
      "entries": [
        {
          "template": "project.hbs",
          "naming": "project.json",
          "selector": ""
        },
        {
          "template": "client.hbs",
          "naming": "{{options.clientName}}.cs",
          "selector": ""
        },
        {
          "template": "definition.hbs",
          "naming": "{{data.name}}.cs",
          "selector": "definitions"
        }
      ]
    }
  }
}

Extend

Custom Templates

As opposed to former gulp-swagger-generator, this new version will support writing custom templates out of the box.

Checkout detailed instructions

Language Pack

As opposed to former gulp-swagger-generator, this new version has been built to make it easy to build support for new languages.

Coming soon.

Clone this wiki locally