express api_使用草率的注释记录您的Express API

express api

Have you ever wanted to have a swagger documentation for your express API based on annotations? I have. And unfortunately didn’t find any way of doing it without having to manually create a swagger.json file. My wish was simple as this: I want to have a clean express app with multiple endpoints and I want to keep swagger documentation for every endpoint close to the endpoint implementation, not in a separate file.

您是否曾经想过基于批注为您的Express API提供详尽的文档？ 我有。 不幸的是，无需手动创建swagger.json文件就找不到任何方法。 我的愿望很简单：我希望有一个带有多个端点的干净的Express应用程序，并且我希望每个端点的草率文档都靠近端点实现，而不是放在单独的文件中。

Maybe I’m just lacking some google skills, but I decided that it’d be much easier for me to create such a tool. And here it is: mgr-swagger-express

也许我只是缺乏一些Google技能，但我认为创建这样的工具会容易得多。 这是： mgr-swagger-express

入门 (Getting started)

Example here will be written in TypeScript, but the same can be done in Javascript project. So imagine a classical express app:

此处的示例将用TypeScript编写，但是在Javascript项目中也可以完成。 想象一下一个经典的快递应用程序：

Here we have a resource “Book” and a some basic CRUD endpoints. The question is “How would you add a cool Swagger documentation to this API?” I really wanted to do it using annotations in order to keep every endpoint documentation close to the endpoint itself.

在这里，我们有一个资源“ Book”和一些基本的CRUD端点。 问题是“您如何向此API添加出色的Swagger文档？” 我真的很想使用注释来做到这一点，以使每个端点文档都靠近端点本身。

This is what you’ll be able to do with mgr-swagger-express: index.ts:

这就是您可以使用mgr-swagger-express ： index.ts ：

BookService.ts:

BookService.ts ：

There is a bot more code, but now we have all swagger documentation laying near the endpoint itself. Let’s see what’s happening here:

有更多的机器人代码，但是现在我们所有的庞大文档都位于端点本身附近。 让我们看看这里发生了什么：

• In index file, we create out express app, as usual. Also we have to initialise all middlewares (the bodyParser being the most important).
  在索引文件中，我们照常创建快递应用程序。 我们还必须初始化所有中间件(bodyParser是最重要的)。

• After this we call the SET_EXPRESS_APP to set the app object globally. This way mgr-swagger-express will be able to attach handlers to endpoints

  此后，我们调用SET_EXPRESS_APP全局设置应用程序对象。 这样，mgr-swagger-express将能够将处理程序附加到端点

• Only after this we can import the service with annotations. It does not have to be a class, it could be just functions.
  只有在此之后，我们才能导入带有注释的服务。 它不必是类，而可以只是函数。
• Then we create an instance of our service (or call an init function in case of not using classes)
  然后，我们创建服务的实例(或在不使用类的情况下调用init函数)
• And we generate swagger config based on all of the annotations we have in the project and attach it to our app using swagger-ui-express package
  然后，我们基于项目中所有的注释生成swagger配置，并使用swagger-ui-express程序包将其附加到我们的应用程序中

Inside the service, there are multiple things going on, but let’s stop on a couple of them only. Everything else you can easily find in the mgr-swagger-express repo:

在服务内部，发生了许多事情，但让我们仅停下来。 您可以在mgr-swagger-express存储库中轻松找到的所有其他内容：

• In the constructor we call addSwaggerDefinition function. It registers a swagger model with a given name. in our case we define BookDefinition under a Book name in order to reference it afterwards by #/definitions/Book

  在构造函数中，我们调用addSwaggerDefinition函数。 它使用给定名称注册一个摇摇欲坠的模型。 在我们的例子中，我们在Book名称下定义BookDefinition ，以便随后通过#/definitions/Book进行引用

• All handlers are annotated with @GET @POST @PUT @DELETE commands. All of them are taking in arguments an object of type SwaggerEndpoint:

  所有处理程序都使用@GET @POST @PUT @DELETE命令进行注释。 所有这些都接受参数SwaggerEndpoint类型的对象：

  path: string;
  auth?: string;
  description?: string;
  tags?: string[];
  parameters?: SwaggerURLParameter[];
  query?: SwaggerQueryParameter;
  body?: SwaggerBodyParameter;
  success?: SwaggerSuccessResponse;

  It’s basically the classical swagger endpoint definition object, nothing special, except for the auth field, but I’ll come back to it in the future

  它基本上是经典的swagger端点定义对象，除了auth字段外没有什么特别的，但是我以后会再讲

  All handlers should have the following signature:

  所有处理程序应具有以下签名：

  (args: object, context: Context) => Promise<any>

  The args object contains all parameters pathed to your endpoint. It can be URL parameters (like book_id in our example), query parameters or even body value.

  args对象包含所有路径到您的端点的参数。 它可以是URL参数(例如我们的示例中的book_id )，查询参数甚至是正文值。

  The context object is used for handling authentication and security, but again, about it later.

  上下文对象用于处理身份验证和安全性，但是稍后再讲。

  结论 (Conclusion)

  Now we have a simple CRUD express API annotated with Swagger and a beautiful swagger UI, where all Swagger definitions are laying nearby the endpoint implementation. As usual — always glad to have any feedback! ️

  现在，我们有了一个简单的CRUD Express API，它带有Swagger注释，还有一个漂亮的swagger UI，其中所有Swagger定义都位于端点实现附近。 和往常一样-总是很高兴收到任何反馈！ ️

翻译自: https://habr.com/en/post/479230/

express api