Skip to content
An open api 3.0 document generator for your javascript project
TypeScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
test
.gitignore
LICENSE
README.md
circle.yml
package.json
tsconfig.json

README.md

Knp Swagger Generator

CircleCI

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.

You can’t perform that action at this time.