FAQ

Table of contents

• General
• Generator Service

GENERAL

How do "tags" affect the generated code?

tags basically groups endpoints into the same API class file. For example, an endpoint with the "store" tags will be generated in the StoreApi class file.

Ref: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#tagObject

Generator Service

https://generator.swagger.io/

The API is split in to two sections: client and server. The endpoints under client are meant for generating code to consume an API. The endpoints under server are meant for generating code to run the API itself (server stubs etc).

Each section has 4 endpoints

• Get a list of languages/frameworks that you can generate code for
• Get options schema for a language/framework (where do these options go? options in GeneratorInput?)
• Post GeneratorInput to generate code to a zip file and get back link to file
• Get zip file (download)

Example node script to generate typescript angular client from swagger.yaml. Note that we use http. Request cannot verify the first certificate if using https (at the time of writing this)

var fs = require('fs');
var path = require('path');
var jsYaml = require('js-yaml');
var request = require('request');
var unzip = require('unzip2');

var codeGenEndpoint = 'http://generator.swagger.io/api/gen/clients';
var language = 'typescript-angular';

fs.readFile(path.resolve('swagger.yaml'), 'utf8', function (error, yaml) {
    if (error) {
        throw error;
    }

    var swaggerObj = jsYaml.load(yaml);

    var postBody = {
        spec: swaggerObj,
        options: {
            modelPropertyNaming: 'camelCase',
            apiPackage: 'api.clients.settings',
            modelPackage: 'api.clients.settings'
        }
    };

    request.post({
        url: codeGenEndpoint + '/' + language,
        body: JSON.stringify(postBody),
        headers: {
            'Content-Type': 'application/json'
        }
    }, function(error, response, body){
        if (error) {
            throw error;
        }

        if (response.statusCode !== 200) {
            throw new Error('Response code was not 200. ' + body)
        }

        var responseObj = JSON.parse(body);

        request({
            url: responseObj.link,
            encoding: null
        }).pipe(unzip.Extract({ path: 'src/client/js/codegen/settingsApi'}));
    });
});