32

Golang,NodeJS(express和nestjs)自动生成swagger

 6 years ago
source link: https://studygolang.com/articles/18734?amp%3Butm_medium=referral
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

Golang 自动生成swagger

  1. 安装
    go get -u github.com/swaggo/swag/cmd/swag
  2. 在项目下执行 swag init ,会生成docs目录。如果目录存在则会报错。
  3. docs目录下会生成docs.go，swagger.json和swagger.yaml，根据需求使用。

Gin 集成例

  • main.go
// @title Sample Service API
// @version 1.0
// @description Platform API for Sample.

// @contact.name getsu
// @contact.url http://www.swagger.io/support
// @contact.email [email protected]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host sample.com
// @BasePath /api
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
func setupRouter() *gin.Engine {
    r := gin.Default()
    r.Run()
}
  • Controller.go
//CreateApp create app
// CreateApp godoc
// @Summary create app
// @Description create app
// @Accept  json
// @Produce  json
// @Param app body dao.App true "create app"
// @Success 200 {object} App
// @Failure 400 {object} Response
// @Failure 500 {object} Response
// @Router /app [post]
// @Security ApiKeyAuth
func CreateApp(c *gin.Context) {
   //略
}

NodeJS 自动生成swagger

Express框架集成

  1. 安装
npm i express-swagger-generator --save-dev
  1. 代码例:
  • main.js
var express = require('express');
var bodyParser = require('body-parser');
var controller = require('./controller');

const config = require('./config/config');

var app = express();
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));
const expressSwagger = require('express-swagger-generator')(app);

let options = {
    swaggerDefinition: {
        info: {
            description: 'This is a sample server',
            title: 'Swagger',
            version: '1.0.0',
        },
        host: 'localhost:3000',
        basePath: '/v1',
        produces: [
            "application/json",
            "application/xml"
        ],
        schemes: ['http', 'https'],
        securityDefinitions: {
            JWT: {
                type: 'apiKey',
                in: 'header',
                name: 'Authorization',
                description: "",
            }
        }
    },
    route: {
        url:'/swagger',
        docs:'/swagger.json',    //swagger文件 api
    },
    basedir: __dirname, //app absolute path
    files: ['./controller/*.js'] //Path to the API handle folder
};
expressSwagger(options)
app.listen(config.port);
  • controller/api.js
/**
 * api for get request
 * @route GET /api/run
 * @returns {object} 200 - An array of user info
 * @returns {Error}  default - Unexpected error
 */
exports.doGet = function(req, res) {
    res.setHeader('Content-Type', 'application/json;charset=utf-8');
    res.send({ result: true, message: 'ok' });
};

/**
 * api for post request
 * @route POST /api/run
 * @returns {object} 200 - An array of user info
 * @returns {Error}  default - Unexpected error
 */
exports.doPost = function(req, res) {
    res.setHeader('Content-Type', 'application/json;charset=utf-8');
    res.send({ result: true, message: 'ok' });
};

NestJS 集成

  1. 安装
npm i --save @nestjs/swagger
During the examination of the defined controllers, the SwaggerModule is looking for all used @Body(), @Query(), and @Param() decorators in the route handlers.

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { ApplicationModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(ApplicationModule);

  const options = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);

  await app.listen(3001);
}
bootstrap();

report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK