DEPRECATED

Unfortunately we decided to not maintain this project anymore (see why). If you want to mark another package as a replacement for this one please send an email to hello@knplabs.com.

Knp Swagger Generator

Generate a full open api document 3.0 generator with a simple suit of function call.

Before starting you can find a complete documentaion about swagger and open api here.

Installation

You can install this libary with NPM:

$ npm install knp-swagger-generator

You diretcly use it with NodeJS or your favorite javascript bundler:

With NodeJS

const swagger = require('knp-swagger-generator').swagger;

const generator = swagger('test', '1.0');

// Your api definitions ...

const openApiDocument = generator.generate();

With harmony modules (typescript, es6 ...)

import swagger from 'knp-swagger-generator';

cons generator = swagger('test', '1.0');

// You api definition here ...

const openApiDocument = generator.generate();

Usage

This libary helps you to create your open api document.

Generate API informations

You can generate api informations with Builder::info:

import swagger from 'knp-swagger-generator';

const generator = swagger('test', '1.0');

/*
 * This line will display a json like:
 *
 * {
 *    "openapi": "3.0",
 *    "info": {
 *      "title": "test",
 *      "version": "1.0"
 *    }
 * }
 */
console.log(generator.generate());


// Alternativly you can call:
generator.info({
    title: 'My Project',
});

console.log(generator.generate());

Generate an api server

In order to generate a server for your open api document use Builder::server:

import swagger from 'knp-swagger-generator';

const generator = swagger('test', '1.0');

generator.server({
    url: 'http://my-api.com',
});

console.log(generator.generate());

Generate an api tag

You can use Builder::tag:

import swagger from 'knp-swagger-generator';

const generator = swagger('test', '1.0');

generator.tag({
    name: 'Videos',
    description: 'Find here all about video management'
});

console.log(generator.generate());

Generate paths

You can use the following methods in order to document your api paths:

An example with get:

import swagger from 'knp-swagger-generator';

const generator = swagger('test', '1.0');

generator.get('/videos', {
    description: 'Retrieve videos',
    responses: {
        '200': {
            description: 'A list of videos'
        }
    }
});

console.log(generator.generate());

Using references

You can define top level model and reference them later. For more informations see:

import swagger from 'knp-swagger-generator';

const generator = swagger('test', '1.0');

// Create a Video model
generator.model('Video');
generator.property('Video', 'id', {
    type: 'number',
});
generator.property('Video', 'title', {
    type: 'string',
});

// Declare a response
generator.response('video_success', {
    description: 'A success video resposne',
    content: {
        'application/json': {
            schema: generator.ref.model('Video')
        }
    }
});

// Declare a parameter
generator.parameter('id', {
    description: 'A unique resource identifier',
    type: 'string',
    in: 'path'
});

// Use them inside a path
generator.get('/videos/{id}', {
    description: 'Retrieve a video',
    parameters: [
        generator.ref.parameter('id'),
    ],
    responses: {
        200: generator.ref.response('video_success'),
    }
});

// Finaly generate your open api document:
console.log(generator.generate());

Using typescript

This library is distributed with typescript definitions, no need to install or declare a module in order to use it, just install it and start using it.

KnpLabs/knp-swagger-generator