rest nodejs_如何将大张旗鼓添加到nodejs rest api

rest nodejs

API development has become an integral part of any web development. API’s are the ones which decouple the server and the client. With the advent of REST APIs, it has become more common to consume JSON response on the UI side. You can enable CORS and even make cross-domain requests as well. Most of the time the same person doesn’t build or work on them. It’s very difficult for the frontend team to consume the APIs that don’t have proper documentation.

API开发已成为任何Web开发的组成部分。 API是使服务器和客户端脱钩的API。 随着REST API的出现，在UI端使用JSON响应已变得越来越普遍。 您可以启用CORS，甚至还可以发出跨域请求。 在大多数情况下，同一个人不会建立或工作于他们。 对于前端团队来说，使用没有适当文档的API非常困难。

So, it's very important to write documentation for your APIs so that whoever consumes those understand them, implement them, and play around with them. Swagger simplifies API development for users, teams, and enterprises with the Swagger open source and professional toolset.

因此，为您的API编写文档非常重要，以便任何使用这些API的人都可以理解，实现和使用它们。 Swagger通过Swagger开源和专业工具集简化了用户，团队和企业的API开发。

In this post, we will see how we can use Swagger with the Nodejs REST API with an example project.

在本文中，我们将看到如何通过示例项目将Swagger与Nodejs REST API结合使用。

• Prerequisites

  先决条件

• Example Project

  示例项目

• Implementation

  实作

• Demo

  演示版

• Summary

  摘要

• Conclusion

  结论

先决条件 (Prerequisites)

There are some prerequisites you need to know before starting this project. You should install nodejs on your machine to run it on your machine. You need to know about nodemon for the development environment.

开始此项目之前，您需要了解一些先决条件。 您应该在计算机上安装nodejs才能在计算机上运行它。 您需要了解有关开发环境的nodemon。

• NodeJS

  节点JS

• Nodemon

  Nodemon

• Swagger

  昂首阔步

npm install nodemon --save-dev
npm install swagger-jsdoc swagger-ui-express --save

示例项目 (Example Project)

This is a simple example nodejs API which has 4 API calls. This is a simple todo application where you can add, edit, delete, and update some tasks. Here is the complete example with swagger documentation.

这是一个简单的示例nodejs API，具有4个API调用。 这是一个简单的待办事项应用程序，您可以在其中添加，编辑，删除和更新某些任务。 这是swagger文档的完整示例。

Example Project 示例项目

Here is the Github link where you can clone and run it on your machine.

这是Github链接，您可以在其中链接并在计算机上运行它。

// clone the project
git clone https://github.com/bbachi/nodejs-api-swagger.git// install and run the project
npm install
npm run dev

实作 (Implementation)

Let’s see how we can add swagger docs to the Nodejs REST API. Consider the below Rest API with 4 HTTP operations post, get, delete, and put.

让我们看看如何将大量文档添加到Nodejs REST API。 考虑以下带有4个HTTP操作post，get，delete和put的Rest API。

server.js server.js

The first thing we need to do is to install swagger related dependencies with the following command.

我们需要做的第一件事是使用以下命令安装与swagger相关的依赖项。

npm install swagger-ui-express swagger-jsdoc --save

There are two things you need to understand before implementing swagger docs to your REST API.

在将svagger文档实现到REST API之前，需要了解两点。

Swagger.json (Swagger.json)

The first thing is to add the file swagger.json to define the operations. You can define schemas for the request and response objects, you can define in parameters and body and descriptions of each Http operation, etc.

第一件事是添加文件swagger.json来定义操作。 您可以为请求和响应对象定义模式，可以在参数和正文以及每个Http操作的描述中进行定义，等等。

swagger.json swagger.json

You can actually see the schemas as well in the swagger page of the Nodejs Rest API.

实际上，您还可以在Nodejs Rest API的醒目的页面中看到这些架构。

Schemas 模式

自定义CSS (Custom CSS)

You can have your own custom CSS for your swagger docs Rest API. You need to define the swagger.css file where you can put all your CSS that can be applied to the Swagger page.

您可以为庞大的文档Rest API使用自己的自定义CSS。 您需要定义swagger.css文件，您可以在其中放置所有可以应用于Swagger页面CSS。

swagger.css swagger.css

Without CSS the swagger screen looks like this.

如果没有CSS，那么屏幕就会像这样。

Without CSS 没有CSS

With custom CSS the swagger screen looks like this.

使用自定义CSS时，屏幕显示如下。

With Custom CSS 使用自定义CSS

Once you have the these files swagger.json and swagger.css in place, it’s time to add the swagger related code in the server.js.

将这些文件swagger.json和swagger.css放置到位后，就该在server.js中添加与swagger相关的代码了。

// import library and filesconst swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const customCss = fs.readFileSync((process.cwd()+"/swagger.css"), 'utf8');// let express to use this
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {customCss}));

Here is the complete server.js file

这是完整的server.js文件

server.js server.js

You can start the project in the development environment with the following command.

您可以使用以下命令在开发环境中启动项目。

npm run dev

演示版 (Demo)

Here is the complete demo where you can execute all the calls through the swagger docs. You can access the swagger page with this URL http://localhost:3080/api-docs/

这是完整的演示，您可以在其中通过swagger文档执行所有调用。 您可以使用以下URL访问招摇页面http：// localhost：3080 / api-docs /

Demo 演示版

摘要 (Summary)

• API development has become an integral part of any web development. API’s are the ones which decouple the server and the client.
  API开发已成为任何Web开发的组成部分。 API是使服务器和客户端脱钩的API。
• It’s very important to write documentation for your APIs so that whoever consumes those understand them, implement them, and play around with them.
  为您的API编写文档非常重要，以便任何使用这些API的人都可以理解，实现和使用它们。
• Swagger simplifies API development for users, teams, and enterprises with the Swagger open source and professional toolset.
  Swagger通过Swagger开源和专业工具集简化了用户，团队和企业的API开发。

• You can define all the operations in the file swagger.json. You can also write this file in the YAML format.

  您可以在文件swagger.json.定义所有操作swagger.json. 您也可以使用YAML格式写入此文件。

• You can have your custom CSS for your swagger page. You can define that CSS in any file. You need to pass this file in the options object.
  您可以为您的招摇页面使用自定义CSS。 您可以在任何文件中定义该CSS。 您需要在options对象中传递此文件。

• You can find the full documentation here.

  您可以在此处找到完整的文档。

• You can find the reference for your swagger.json here.

  您可以在此处找到swagger.json的参考。

结论 (Conclusion)

Always document your APIs so that it can be easy to test and it’s easy for other to understand your API well and test it as well. Swagger simplifies API development for users, teams, and enterprises with the Swagger open source and professional toolset.

始终记录您的API，以便易于测试，其他人也容易理解您的API并对其进行测试。 Swagger通过Swagger开源和专业工具集简化了用户，团队和企业的API开发。

翻译自: https://medium.com/bb-tutorials-and-thoughts/how-to-add-swagger-to-nodejs-rest-api-7a542cfdc5e1

rest nodejs