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

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

开始使用

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

在这里，我们有一个资源“ Book”和一些基本的CRUD端点。 问题是“如何向此API添加很酷的Swagger文档？”我真的想使用注释来做到这一点，以使每个端点文档都与端点本身保持紧密联系。

这就是您可以使用mgr-swagger-express进行的操作 ：
index.ts ：

BookService.ts ：

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

• 在索引文件中，我们照常创建快递应用。 同样，我们必须初始化所有中间件（bodyParser是最重要的）。
• 此后，我们调用SET_EXPRESS_APP以全局设置应用程序对象。 这样，mgr-swagger-express将能够将处理程序附加到端点
• 只有在此之后，我们才能导入带有注释的服务。 它不必是类，而可以只是函数。
• 然后，我们创建服务的实例（或在不使用类的情况下调用init函数）
• 然后，我们基于项目中所有的注释生成swagger配置，并使用swagger-ui-express程序包将其附加到我们的应用程序中

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

• 在构造函数中，我们调用addSwaggerDefinition函数。 它使用给定名称注册一个摇摇欲坠的模型。 在我们的例子中，我们在Book名称下定义BookDefinition ，以便随后通过#/definitions/Book进行引用
• 所有处理程序都使用@GET @POST @PUT @DELETE命令进行注释。 所有这些都接受参数SwaggerEndpoint类型的对象：
  

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

  
  

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

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

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

  
  

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

  
  
  

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

  
  

  结论

  
  

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