swagger开心的swagger


备注

本节概述了什么是swagger,以及开发人员可能想要使用它的原因。

它还应该提到招摇中的任何大型主题,并链接到相关主题。由于swagger文档是新的,您可能需要创建这些相关主题的初始版本。

简介 - 安装 - 设置(在Node.js中开发)

介绍:

Swagger是一组描述REST API的格式的规则/规范。它为代码生成器和编辑器等正式规范提供了强大且积极开发的工具生态系统。 Swagger的最佳部分是将方法,参数和模型的文档紧密集成到服务器代码中,从而使API始终保持同步。这是一个链接,简要概述了什么是swagger:入门。

写作规格:

规范可以用JSON或YAML编写。因此我们相应地制作了swagger.json或swagger.yaml文件。在线编辑器可用于创建文件。这是一个描述规范语法的链接: http//swagger.io/specification/

使用招摇的方法:

  1. API优先方法(自上而下方法):使用swagger编辑器→编写swagger定义→使用swagger-codegen和swagger-ui生成API
  2. 服务优先方法(自下而上方法):使用swagger注释开发JAX-RS资源类→使用swagger-core自动生成swagger定义→使用swagger-codegen和swagger-ui生成客户端API和文档。以上可以在swagger maven插件期间的maven构建期间完成。

安装和设置

在本节中,我们将安装swagger,设置swagger UI并使用它生成服务器端和客户端SDK。要使用Node包管理器安装swagger,请执行以下命令:

npm install -g swagger

使用'-g'标志将确保模块全局安装。接下来,我们将使用以下命令创建项目:

swagger project create <project-name>

这将要求用户选择用于开发REST API的框架。 Express可以选择相同的。这将创建项目目录,其中包含以下各项以及每个项目中的README.md文件:

  • API /
    • 控制器/
    • 助手/
    • 嘲笑/
    • 昂首阔步/
  • 配置/
  • 测试/
    • API /
      • 控制器/
      • 助手
  • app.js
  • 的package.json

服务器现在基本就绪,可以使用此命令在项目根目录中执行:

swagger project start

如果主机服务器设置为localhost 且未在app.js 文件中修改端口号,则服务器app.js 以下位置启动: http://localhost:10010 现在,可以使用swagger UI进一步开发REST API。这可以通过以下方式在新终端中启动:

swagger project edit

这将在随机生成的端口上的浏览器选项卡中打开swagger编辑器。可以看到示例hello GET请求已存在于swagger.yaml文件中。对此文件的任何进一步更改都将导致服务器自行重新启动。

在paths部分中,用于x-swagger-router-controller 应该是controllers文件夹中的javascript文件名。作为示例,hello_world.js应该出现在controllers目录中。此外, operationId 参数的值表示上述javascript文件中的函数名称。这是应该编写业务逻辑的地方。因此,我们的swagger设置已完成,可用于进一步开发我们的API。