swagger-schema

swagger-ui schema auto generation and base on swagger-autogen.

Installation

This is a Node.js module available through the npm.

$ npm install --save swagger-schemagen

It is loaded using the require() function:

const swaggerSchema = require('swagger-schemagen')

Update

If you already have the module installed and want to update to the latest version, use the command:

$ npm install --save swagger-schemagen@last

Usage

Example express api

Usage

Function signature:

const swaggerSchema: (outputFile: <string>, schemaFolder: <Array of string>) => Promise <any>

outputFile: (Required*). Output file. It will be the file generated by the module containing the documentation in the format identified by Swagger.

schemaFolder: (Required*). This Folder is saving all of schema json file, and the parameter's type for mssql will update in Swagger file.

The code below must be inserted in a separate file, for example: swagger.js. For example:

File: swagger.js

const doc = {
    info: {
        title: "Example API Document",
        description: "Description"
    },
    host: null,
    schemes: ['http'],
    tags: alltags
}

const outputFile = './src/swagger/swagger-output.json'
const endpointsFiles = ['./index.js']

const swaggerschema = require('./src/lib/swaggerschema')
const schematest = require('swagger-schemagen')

const asyncfun = async (outputFile, endpointsFiles, doc, schemaFolder) => {
    await swaggerAutogen(outputFile, endpointsFiles, doc)
    await schematest(outputFile, schemaFolder)
}

const schemaFolder = './src/schema/'
asyncfun(outputFile, endpointsFiles, doc, schemaFolder)

Example Document

Json file in schema folder

Note.json:

[
    { "attr": "vid", "type": "Int" },
    { "attr": "currenttime", "type": "Float" },
    { "attr": "nid", "type": "Int" },
    { "attr": "title", "type": "NVarChar" },
    { "attr": "content", "type": "NVarChar" }
]

Notice

Swagger schema json file and swagger tag should be give in same name!!!

Like your router's swagger tag is 'Note', and your schema name should be 'Note.json'.

Compare Use

Before Using swagger-schema

controller -> Note.js:

router.delete('/note', async (req, res, next) => {
    // #swagger.tags = ['Note']
    // #swagger.summary = '刪除單個筆記'
    const { nid } = req.body // declare parameter's in body
    sqlcode = "update Note set bDel = 1 where NID = @nid and OwnerMID = @mid";
    let response = await runSQL(sqlcode, req, schema);
    res.json(response ? { message: "success" } : { message: "failed" });
});

router.put('/note/title', async (req, res, next) => {
    // #swagger.tags = ['Note']
    // #swagger.summary = '編輯筆記標題'
    const { nid, title } = req.body // declare parameter's in body
    sqlcode = "update Note set Title = @title, LastModifiedDT = getdate() where NID = @nid and OwnerMID = @mid";
    let response = await runSQL(sqlcode, req, schema);
    res.json(response ? { message: "success" } : { message: "failed" });
});

After Using swagger-schema

schema file: