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.
You can install this libary with NPM:
$ npm install knp-swagger-generator
You diretcly use it with NodeJS or your favorite javascript bundler:
const swagger = require('knp-swagger-generator').swagger;
const generator = swagger('test', '1.0');
// Your api definitions ...
const openApiDocument = generator.generate();
import swagger from 'knp-swagger-generator';
cons generator = swagger('test', '1.0');
// You api definition here ...
const openApiDocument = generator.generate();
This libary helps you to create your open api document.
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());
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());
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());
You can use the following methods in order to document your api paths:
Builder::get
Builder::post
Builder::patch
Builder::put
Builder::delete
Builder::options
Builder::head
Builder::trace
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());
You can define top level model and reference them later. For more informations see:
Builder::model
Builder::property
Builder::parameter
Builder::response
Builder::requestBody
Builder::example
Builder::header
Builder::security
Builder::link
Builder::callback
-
Builder::ref
:
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());
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.