将 swagger 添加到我的 Nodejs Restify 项目

问题描述 投票：0回答：4

我有一个基本的 Nodejs Restify 服务器，有两种简单的方法：一种是 GET，一种是 POST。我正在尝试在我的 Restify 服务之上添加 swagger API 文档。找到了对快递的支持。

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

我的基本 Restify 代码如下。

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'},function(req,res,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)
})
node.js swagger restify
4个回答
2
投票

所以我确实设法将 Swagger 文档添加到我的 Node.js 和 Restify api 中。我希望有人觉得这很有帮助，并且没有什么被弃用的。

所以我使用的包叫做

restify-swagger-jsdoc
而且配置非常简单，您将需要

https://www.npmjs.com/package/restify-swagger-jsdoc

npm i restify-swagger-jsdoc

然后在初始化的文件中添加以下代码片段

const server = restify.createServer()


一旦你运行你的服务器，并且你的 jsdoc swagger 注释和注释被添加到你的路由中，你应该能够在上面提到的路径中查看生成的 Swagger 文档。

    





    

    
    
    

    

        

            

                

                    
1
投票

                    
                

            

        

        
const restifySwaggerJsdoc = require('restify-swagger-jsdoc');

restifySwaggerJsdoc.createSwaggerPage({
  title: 'API documentation',
  version: '1.0.0',,
  server: server, // created restify server object,
  path: '/api-docs', // url to view generated docs,
  apis: ['./src/routes/*.js'], // this is where swagger can find 
                               // files containing jsdoc or can point 
                               // to api.yaml file
                               // to generate docs from. 
});


 文档：
swagger-restify

    



    

    
    
    

    

        

            

                

                    
1
投票

                    
                

            

        

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

...
swagger.init(server, { // set up swagger for "server"
    apiVersion: '1.0',
    swaggerVersion: '1.0',
    swaggerURL: '/docs', // endpoint what you want to access
    swaggerJSON: '/api-docs.json',
    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.listen(5000,function(){
    console.log("Starting server at :%s,%s",server.url,server.name)
})

 文档，初始化 swagger 时，需要将 
swagger-restify
 属性作为数组传递，其中包含 API 定义文件名及其相对路径。
API定义可以通过使用jsdoc注释或创建yml文件来完成
可以通过参考 
apis
 文档获得 API 定义创建的清晰思路，因为它包含两种方法的示例。
此外，您需要将 swagger UI 相关的 HTML 组件添加到提供静态内容的文件夹中，并且需要将路径作为 
swagger-restify
 属性包含在 swagger 配置中。
对于以下代码段，我假设它们位于 ./public 文件夹中。


像这样配置服务器，


swaggerUI

    



    

    
    
    

    

        

            

                

                    
0
投票

                    
                

            

        

        


逐步集成




    安装所需的软件包
首先，您需要安装必要的软件包。打开终端并运行以下命令：
  1. 

    npm 我 swagger-jsdoc
    

    npm 我 swagger-ui-express
    

    

    2. 在 server.js 中设置 Swagger
接下来，导入包并在主服务器文件 (server.js) 中配置 Swagger：
  2. 

    const swaggerJSDoc = require('swagger-jsdoc');
    

    const swaggerUi = require('swagger-ui-express');
    

    

    

    3. 添加以下代码来设置 Swagger：


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'},function(req,res,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 规范并在 /api-docs 端点提供文档。




记录您的 API 端点
现在，您可以直接在 server.js 文件中添加 Swagger 注释来记录您的 API 端点。
    

  1. 

    2. 对于 GET API：


// Swagger Code
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API documentation for project',
      version: '1.0.0'
    },
    servers: [
      {
        url: 'http://localhost:3333/'
      }
    ]
  },
  apis: ['./server.js']
}

const swaggerSpec = swaggerJSDoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));



对于 POST API：


/**
 * @swagger
 *  /api/users:
 *      get:
 *          summary: Get all users
 *          description: Retrieve a list of all users
 *          responses:
 *              200:
 *                  description: Successfully retrieved list of users
 *                  content:
 *                      application/json:
 *                          schema:
 *                              type: array
 *                              items:
 *                                  type: object
 *                                  properties:
 *                                      id:
 *                                          type: integer
 *                                          description: The user ID
 *                                      name:
 *                                          type: string
 *                                          description: The user's name
 */



将 /route-name 替换为您的实际路线。


结论
将 Swagger API 文档集成到 Node.js 项目中有助于简化 API 开发并改善协作。通过执行这些步骤，您可以轻松设置交互式文档，并确保您的 API 文档齐全且易于使用。


如果您有任何疑问或需要进一步帮助，请随时联系！

    

	

    

    


  

  

    
最新问题


  





  

    © www.soinside.com 2019 - 2024. All rights reserved.