swagger-generator-json

SWAGGER GENERATOR JSON

Library generate json use for swagger-ui-express

Quick start

Example for 1 method in document:

// example.js file

const { DType, Response, Operation, API } = require('swagger-generator-json')
// By default will be get method
const documentsSearchUser = new API({
    path: '/public/users/search',
    operation: [
        new Operation({
            method: DType.get,
            parameters: [
                {
                    name: 'username',
                    type: DType.string,
                    place: DType.query,
                    description: "Username must be required"
                }
            ],
            responses: [
                new Response({
                    schema: [{
                        id: DType.number,
                        name: DType.string,
                        isAdmin: DType.boolean
                    }]
                }),
                new Response({
                    code: 302,
                    schema: [{
                        id: DType.number,
                        name: DType.string,
                        isAdmin: DType.boolean
                    }]
                })
            ],
            tags: 'public/user'
        })
    ]
})

Example for multi method in document:

// example.js file

const { DType, Response, Operation, API } = require('swagger-generator-json')
// GET method
const operationGet = new Operation({
    method: DType.get,
    parameters: [
        {
            name: 'token',
            type: DType.string,
            place: DType.body,
            description: "Token need to authenticate"
        },
        {
            name: 'userid',
            type: DType.string,
            place: DType.path,
            description: "Only number"
        }
    ],
    responses: [
        new Response({
            schema: [{
                id: DType.number,
                name: DType.string,
                isAdmin: DType.boolean
            }]
        })
    ],
    summary: "API GET USER",
    tags: 'public/user'
})

// POST method
const operationPost = new Operation({
    method: DType.post,
    parameters: [
        {
            name: 'token',
            type: DType.string,
            place: DType.header,
            description: "Token need to authenticate"
        }
    ],
    responses: [
        new Response({
            schema: {
                id: DType.number,
                name: DType.string,
                isAdmin: DType.boolean
            },
        })
    ],
    tags: 'public/user',
    summary: "API CREATE USER"
})

const documentsPublicUser = new API({
    path: '/public/users',
    operation: [operationGet, operationPost]
})

Export to use

module.exports = [documentsPublicUser, documentsSearchUser]

Create instance Document

// document.js file
const paths = require('./example')
const { Document } = require('swagger-generator-json')

module.exports = new Document({
    description: `This is the Devteam's documents of project`,
    version: "1.0.0",
    title: "App Name",
    paths
})

Use with swagger-ui-express

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./document');
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Some example for request (schema), params (type):

// Data response
const data = {
    status: true,
    message: "Success",
    list: [
        {
            username: "devteam",
            isAdmin: "true",
            age: 25
        }
    ]
}
// Convert to schema
new Response({
    schema: {
        status: DType.boolean,
        message: DType.string,
        list: [
            {
                username: DType.string,
                isAdmin: DType.boolean,
                age: DType.number
            }
        ]
    }
})

const param = [
        {
            name: 'list',
            type: {
                userid: DType.number,
                list: [{
                    productId: DType.number,
                    price: DType.number
                }]
            },
            place: DType.body,
            description: "User's orders"
        }
    ]