在 Deno 中，我们可以使用 swagger-jsdoc 这个工具来自动生成 API 文档。swagger-jsdoc 是一个基于 JSDoc 注释生成 Swagger 规范的工具，它可以根据注释中的 API 信息自动生成 Swagger 文档。本文将介绍如何使用 swagger-jsdoc 在 Deno 中生成 API 文档。
安装 swagger-jsdoc
首先，我们需要安装 swagger-jsdoc 和 swagger-ui-express 这两个包，它们分别用于生成 Swagger 规范和展示 Swagger 文档。可以使用以下命令进行安装：
deno install --allow-net --allow-read --allow-write --unstable https://deno.land/x/install/install.ts deno install --unstable --allow-read --allow-write --allow-net https://deno.land/x/denon/denon.ts
npm install swagger-jsdoc swagger-ui-express
配置 swagger-jsdoc
在项目中的入口文件中添加以下代码：
-- -------------------- ---- -------
------ ------------ ---- ----------------
----- ----------------- - -
-------- --------
----- -
------ ---- ---------------
-------- --------
------------ ---- ------------- --- -- -----
--
-------- -
-
---- ------------------------
------------ ------------ --------
--
--
--
----- ------- - -
------------------
----- ----------------------
--
----- ----------- - ----------------------上述代码中，我们定义了 swaggerDefinition 对象，包含了 API 的基本信息，如版本、描述、服务器等。然后，我们定义了 options 对象，它包含了 swaggerDefinition 和 API 的路由信息。最后，我们使用 swaggerJSDoc 方法生成了 Swagger 规范。
配置 Swagger UI
我们需要配置 Swagger UI 来展示生成的 API 文档。可以在项目中添加一个名为 swagger.js 的文件，内容如下：
import swaggerUi from 'swagger-ui-express';
export default function (app) {
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
}上述代码中，我们使用 swaggerUi.serve 和 swaggerUi.setup 方法来配置路由和展示 Swagger 文档的页面。
注释 API
在我们的路由和控制器中添加 JSDoc 注释，swagger-jsdoc 将根据这些注释来生成 Swagger 规范。以下是一个示例路由和控制器：
-- -------------------- ---- -------
------ - ------- ------- - ---- ---------------------------------
----- ------ - --- ---------
---
- --------
- -------
- ----
- -------- --- --- -----
- ------------ --- --- ----- ---- --- --------
- ----------
- ----
- ------------ - ---- -- -----
- --------
- -----------------
- -------
- ----- -----
- ------
- ----- ---------------------------
--
-------------------- ----- ----- -------- -- -
----------------- - -
-
--- --
----- ----- -----
--
-
--- --
----- ----- -------
--
--
---
------ ------- -------在上述代码中，我们使用了 @swagger 注释来描述 API 的信息。swagger-jsdoc 将根据这些注释自动生成 Swagger 规范。
运行应用程序
现在，我们可以运行我们的应用程序，并在浏览器中访问 http://localhost:3000/api-docs 来查看自动生成的 API 文档。
-- -------------------- ---- ------- ------ - ----------- - ---- --------------------------------- ------ ------ ---- ------------------------ ------ ------- ---- --------------- ----- --- - --- -------------- ------------------------- --------------------------------- ------------- ------------------- ------- -- ------------------------ ----- ------------ ----- ---- ---
结论
使用 swagger-jsdoc 可以帮助我们自动生成 API 文档，使我们的 API 更加规范化和易于使用。在 Deno 中，我们可以轻松地使用 swagger-jsdoc 来生成 Swagger 规范，并使用 swagger-ui-express 来展示 Swagger 文档。希望本文能对您有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/673a977c39d6d08e88aed9de