swagger编写api_使用swagger在Node JS中自动编写API文档

swagger编写api

Original article in Portuguese Brazil: (Click here)

巴西葡萄牙语原文：( 点击这里 )

For those who develop APIs in Node.js, whether at a professional level or not, you know that keeping the project documentation up to date is not an easy task, especially with short deadlines and other priorities, the documentation ends up most of the time getting out of date or even ignored. To resolve this, today I’m going to talk about an NPM module for Node.js that automatically performs the documentation for Swagger whenever your project is started, without you having to keep doing repairs or touch-ups on the Swagger .json file. The module in question is swagger-autogen.

对于那些在Node.js中开发API的人员，无论是否处于专业水平，您都知道保持项目文档的更新不是一件容易的事，尤其是在期限短和其他优先级高的情况下，文档大部分时间会失效过时甚至被忽略。 为了解决这个问题，今天我将讨论Node.js的NPM模块，该模块在您启动项目时就自动执行Swagger的文档，而无需继续对Swagger .json文件进行修复或修改。 有问题的模块是swagger-autogen 。

The swagger-autogen module generates only the Swagger .json file. To interpret it, we will have the help of the swagger-ui-express module and Express.js to create a server, leaving the documentation available on some port. Ah! But does it only work with Express.js? No, the module is independent of any framework, BUT, some frameworks like Express.js (or similar) will have some advantages and we will see more about them later. With the module it is possible to generate the documentation in two ways:

swagger-autogen模块仅生成Swagger .json文件。 为了解释它，我们将借助swagger-ui-express模块​​和Express.js来创建服务器，而将文档保留在某些端口上。 啊! 但这仅适用于Express.js吗？ 不，该模块独立于任何框架，但是，Express.js(或类似框架)之类的某些框架将具有一些优势，我们稍后将详细介绍它们。 使用该模块，可以通过两种方式生成文档：

1. Along with the project, that is, every time the project is started, new documentation is generated, making it always updated.
   与项目一起，也就是说，每次启动项目时，都会生成新的文档，使其始终处于更新状态。

2. Without starting the project, that is, running a script at the root of the project. This is similar to the npm test (testers will know…).

   无需启动项目，即在项目的根目录下运行脚本。 这类似于npm测试 (测试人员会知道...)。

The first one I found more interesting, because it keeps the documentation always updated when we change the code. But I will talk about both ways in this article!

我发现第一个更有趣，因为当我们更改代码时，它可使文档始终保持更新。 但是我将在本文中讨论这两种方式！

The idea of ​​the module is very simple, just indicate the output file (.json) of Swagger, the files containing the endpoints, which are the files containing the get(), post(), etc functions, and a object containing the details of the documentation, such as: version, title, description, schemes, etc., the latter is not mandatory, it already has some standard values. A complete example can be seen at this link: https://github.com/davibaltar/example-swagger-autogen. Well, enough talking and let’s go to the code!

该模块的思想很简单，只需指出Swagger的输出文件( .json )，包含端点的文件，即包含get()，post()等函数的文件以及包含以下内容的对象文档的详细信息，例如：版本，标题，描述，方案等，后者不是强制性的，它已经具有一些标准值。 可以在以下链接中看到完整的示例： https : //github.com/davibaltar/example-swagger-autogen 。 好了，足够多的讨论，让我们看一下代码！

In its simplest form, I will create a project with the following structure:

以最简单的形式，我将创建一个具有以下结构的项目：

|-- package.json
|-- swagger.js
|-- index.js
|-- 

Where index.js is the root file of your project, that is, where execution starts and endpoints.js is the file that contains the .get(), post(), etc functions. The swagger.js file will only be in charge of calling the swagger-autogen module to generate the documentation.

其中index.js是项目的根文件，即执行开始的地方，而endpoints.js是包含.get()，post()等函数的文件。 swagger.js文件仅负责调用swagger-autogen模块以生成文档。

If you already use Express.js (or similar) the good news is that the module automatically recognizes the methods, path, status of responses and content-type of Header! If you don’t use Express.js or similar, I’ll talk about how to resolve this later.

如果您已经使用Express.js(或类似版本)，那么好消息是该模块会自动识别Header的方法，路径，响应状态和内容类型！ 如果您不使用Express.js或类似的东西，我将在稍后讨论如何解决。

For didactic purposes, I will write the index.js file, which will contain a simple structure of a server, looking like this:

出于教学目的，我将编写index.js文件，其中将包含服务器的简单结构，如下所示：

Recalling that in this article we are not looking at API security, good programming practices, MVC standard, versioning or routes. The idea here is to simplify as much as possible so that we can see only the documentation part.

回顾本文，我们不讨论API安全性，良好的编程习惯&#x