将 swagger 添加到我的 nodejs restify 项目中

问题描述

我有一个基本的 nodejs restify 服务器，它有两个简单的方法，一个是 GET，一个是 POST。我正在尝试在我的 restify 服务之上添加 swagger API 文档。找到了对 express 的支持。

还发现了一些库 https://www.npmjs.com/package/swagger-restify 。 但是不知道如何在代码中使用它。如何以某种方式添加它，我所有的 api 文档都会出现在“http://localhost:5000/docs”或类似的内容中。

我的基本代码如下。

var restify=require('restify');
var restifyPlugins = require('restify-plugins');
var cors = require('cors');
var server=restify.createServer({name:'test'});

server.use(restifyPlugins.acceptParser(server.acceptable));
server.use(restifyPlugins.queryParser());
server.use(restifyPlugins.fullResponse());
server.use(restifyPlugins.bodyParser({
    maxBodySize: 0,multiples: true
}));

server.use(cors({
    origin: '*',methods: 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS',credentials:'false',optionsSuccessstatus: 200 /* some legacy browsers (IE11,varIoUs SmartTVs) choke on 204 */,}))

server.use(restifyPlugins.authorizationParser());


server.get({path:'/test'},function(req,res,next){
    
    console.log("TEST API")
    res.send("hello");
    });

server.post({path:'/postCheck'},next){

    console.log("TEST post API",req.body.userId)
    res.send("hello post");
    });



server.listen(5000,function(){
    console.log("Starting server at :%s,%s",server.url,server.name)
})

解决方法

根据 swagger-restify 文档，在初始化 swagger 时，需要将 apis 属性作为带有 API 定义文件名及其相对路径的数组传递。 API 定义可以通过使用 jsdoc 注释或创建 yml 文件来完成 通过参考 swagger-restify 文档可以清楚地了解 API 定义的创建，因为它包含两种方法的示例。

此外，您需要将与 swagger UI 相关的 HTML 组件添加到提供静态内容的文件夹中，并且需要在 swagger 配置中包含路径作为 swaggerUI 属性。

对于以下代码段，我假设它们位于 ./public 文件夹中。

像这样配置服务器，

var restify=require('restify');
var restifyPlugins = require('restify-plugins');
var swagger = require('swagger-restify');
var cors = require('cors');
var server=restify.createServer({name:'test'});

server.use(restifyPlugins.acceptParser(server.acceptable));
server.use(restifyPlugins.queryParser());
server.use(restifyPlugins.fullResponse());
server.use(restifyPlugins.bodyParser({
    maxBodySize: 0,multiples: true
}));


  swagger.init(server,{
    apiVersion: '1.0',swaggerVersion: '1.0',swaggerURL: '/docs',swaggerUI: './public',basePath: 'http://localhost:5000',info: {
      title: 'swagger-restify sample app',description: 'Swagger + Restify = {swagger-restify}'
    },apis: ['./api.js','./api.yml'],middleware: function(req,res){}
  });


server.use(cors({
    origin: '*',methods: 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS',credentials:'false',optionsSuccessStatus: 200 /* some legacy browsers (IE11,various SmartTVs) choke on 204 */,}))

server.use(restifyPlugins.authorizationParser());


server.get({path:'/test'},function(req,res,next){
    
    console.log("TEST API")
    res.send("hello");
    });

server.post({path:'/postCheck'},next){

    console.log("TEST post API",req.body.userId)
    res.send("hello post");
    });  



server.listen(5000,function(){
    console.log("Starting server at :%s,%s",server.url,server.name)
});

,

在启动服务器之前，只需将 swagger 资源设置为 swagger-restify 文档：

// import swagger lib
var swagger = require('swagger-restify');

...
swagger.init(server,{ // set up swagger for "server"
    apiVersion: '1.0',// endpoint what you want to access
    swaggerJSON: '/api-docs.json',res){}
});

server.listen(5000,server.name)
})