什么是 Swagger？
Swagger 是一种使用 OpenAPI 规范构建 API 文档的工具。它允许开发人员描述 API 的行为、参数和输出结果等信息，然后将这些信息格式化成可视化界面的形式，使得 API 的使用者可以直观地了解它的使用方法和行为特征。
Swagger 通过支持多种编程语言和框架，使得开发人员能够轻松地创建和维护 API 文档，并与其他开发人员和 API 的使用者分享和交流。
构建 RESTful API
RESTful API 是目前最常见的 API 设计规范之一，具有易于理解、可扩展性强等特点。接下来，我们将以 Swagger 和 Node.js 框架为例，展示如何使用 Swagger 构建 RESTful API 在线文档。
安装 Swagger
在 Node.js 中，可以使用 npm 包管理工具来安装 Swagger。运行以下命令：
npm install swagger-ui-express swagger-jsdoc
其中，swagger-jsdoc 允许你将 API 文档作为注释集成到代码中，并生成 Swagger 规范格式的 JSON 文件。swagger-ui-express 则使得这个 JSON 文件可以在 web 应用程序中以可视化的形式呈现。
编写 API 文档
创建一个 swagger.js 文件，用于描述 API 文档。以下是一个简单的例子：
-- -------------------- ---- ------- ----- ------------ - ------------------------- ----- ------- - - ----------- - -------- -------- ----- - ------ --- ----- -------- -------- ------------ ---- --- -- ------------ -- -------- - - ---- ----------------------- - -- -- ----- ------------------ -- ----- ----- - ---------------------- -------------- - ------展开代码
其中，我们定义了 API 的基本信息、服务器地址和 API 注释所在文件的路径。最后，我们通过将这些选项传递给 swaggerJsdoc 函数来生成 Swagger 规范。
在此之后，我们需要在代码中添加 Swagger 注释。例如，以下代码为一个添加联系人的 API 路径添加了 Swagger 注释：
-- -------------------- ---- ------- --- - -------- - ---------- - ----- - -------- --- - --- ------- - ------------ ---- - --- ------- -- --- ------- ---- - ------------ - --------- ---- - -------- - ----------------- - ------- - ----- ------------------------------ - ---------- - ---- - ------------ ------- ------- ------------ - -------- - ----------------- - ------- - ----- ------------------------------ -- ------------------------ ----- ---- -- - -- --- ---展开代码
在 Swagger 注释中，我们指定了 API 的请求方式、摘要、描述、请求体、响应体结构等信息。
呈现 API 文档
最后，我们需要在应用程序中呈现 Swagger API 文档。在 Express.js 应用程序中，可以通过 swagger-ui-express 包来实现。以下是一个简单的例子：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- --------- - ------------------------------ ----- ----- - --------------------- ----- --- - ---------- ----- ---- - ----- -------------------- ---------------- ------------------------ ---------------- -- -- - ------------------- ------- -- --------------------------- ---展开代码
这里我们使用了 /api-docs 路径，让 Swagger API 文档在该路径下呈现。
总结
使用 Swagger 和 Node.js 可以轻松地创建和维护 RESTful API 文档，并与其他开发人员和 API 的使用者分享和交流。通过对 API 的行为、参数和输出结果等信息的描述，我们可以实现 API 的可视化展示，使得 API 的使用更加直观和易于理解。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6582e73ed2f5e1655ddf6919
