RESTful API 是目前互联网的主流接口风格，而 Swagger 是一款优秀的自动化 API 文档工具。在前后端分离的开发模式下，接口的规范化和文档化显得尤为重要。本文将详细介绍如何使用 Swagger 生成 RESTful API 接口文档，并包含示例代码，以便读者能更好地应用于实际开发中。
Swagger 是什么
Swagger 是一个规范和完整的框架，用于生成、编写和描述 RESTful API。其旨在使RESTful API文档化、自动生成文档以及更好的客户端-服务器交互。使用 Swagger，API 文档将变得更加可读性和可视性，从而提供更好的用户体验。Swagger 包括了以下三个核心工具：
Swagger Editor：API 文档的编辑和调试。
Swagger UI：RESTful API 的可视化文档界面。
Swagger Codegen：根据 API 文档生成代码库，以便于客户端的访问。
Swagger 具有非常完善的支持库和教程文档，可以在其官网上进行参考和了解，这里就不再展开介绍。
Swagger 的安装和配置
使用 Swagger 需要在项目中安装相关的包，具体可以使用 npm 来安装，如下所示：
npm install swagger-ui-express swagger-jsdoc --save
另外，必须要有一个 YAML 文件来描述 API，通常称之为 Swagger 文档。Swagger 文档的编写可以使用 Swagger Editor 工具，也可以手写。在此处，我们以手写 YAML 文档为例，来讲解如何进行配置。
首先，在项目的根目录下创建一个名为 swagger.yaml 的 YAML 文件，编写如下内容：
-- -------------------- ---- ------- - ---- -------- ----- - --- ------------- ----- -------- ----- ------ ---- ------------ ------- ------- - ----------- ------ ------ - ----------------------- ---- ----- - ---- -------- -------- ----------- - ----- ------ --- ------- ------------ ----------- --------- ----- ----- --------- - ----- ------- --- ------- ------------ --------------- --------- ----- ----- --------- ---------- ---- ------------ ---- ------- ----- ------- ------ ----- -------- ----------- --- ----- --------- ------------ --- --- ----- ----- -------- ------------ ------ ---- ----- --------- ------------ ------展开代码
上述代码中，我们定义了一个 /user 路由，包含了一个 GET 请求，也就是获取用户列表的接口。在接口的配置中，我们可以设置请求参数、返回结果等，非常灵活便利。
接下来，我们需要在项目的初始化文件中加载 Swagger：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- --- - ---------- ----- --------- - ------------------------------ ----- ------------ - ------------------------- ----- ------- - - -- ----- ---- - ------- -- ------------------ --------------------------------------------- -- --- ---- ----- --------------------- -- -- --- --------------- -- ----- ----------- - ---------------------- -------------------- ---------------- ------------------------------展开代码
在上述代码中，我们使用 swagger-jsdoc 加载 Swagger YAML 文件，并使用 swagger-ui-express 加载 Swagger UI 页面。然后，访问 http://localhost:3000/api-docs，可以看到自动生成的接口文档页面。
Swagger 的使用
使用 Swagger 生成 RESTful API 接口文档非常简单。首先，我们需要定义我们的路由，包括方法、参数、返回值等，然后用 Swagger 展示出来。下面是一个获取商品的例子:
-- -------------------- ---- ------- --- - -------- - - ------------ - ---- - -------- --- - ---- -- -- - ------------ --- - ---- -- -- - ----------- - - ----- -- - --- ---- - ------------ -- -- --- ---- - --------- ---- - ------- - ----- ------- - ---------- - ---- - ------------ -- - -------- - ----------------- - ------- - ----- --------------------------- - ---- - ------------ --- ----- -- ------------------------ ---------- ---- -- - -- --- ---展开代码
上述代码中，我们使用 @swagger 注解定义了一个 /goods/{id} 路由，并使用 swagger-ui-express 将 Swagger 展示在页面上。其余部分则是我们熟悉的路由定义。
Swagger 支持的注解很多，可以根据实际情况进行选择。这些注解可以让我们在代码中标识哪些接口需要写入 Swagger 文档，Swagger 会自动读取这些注解，并生成相应的接口文档。
结语
使用 Swagger 生成 RESTful API 接口文档可以大大提高接口的可读性和可视性，从而提供更好的用户体验。本文详细介绍了 Swagger 的安装和配置，以及在代码中使用 Swagger 的方法。希望读者可以掌握 Swagger 的使用方法，并应用于实际的开发中。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/67c4463d6e1fc40e36d2b2a0
