在开发 Web 应用程序时，API 文档是必不可少的。API 文档可以帮助开发人员了解如何使用 API，从而提高开发效率和降低开发成本。Swagger 是一个流行的 API 文档工具，它可以帮助开发人员快速构建和维护 API 文档。本文将介绍如何在 Deno 中使用 Swagger 构建 API 文档。
什么是 Deno？
Deno 是一个用于 JavaScript 和 TypeScript 的运行时环境，它由 Node.js 的创始人 Ryan Dahl 开发。与 Node.js 不同的是，Deno 支持 TypeScript，不需要安装任何依赖项，具有更好的安全性和性能。
什么是 Swagger？
Swagger 是一个开源的 API 文档工具，它可以帮助开发人员快速构建和维护 API 文档。Swagger 使用 OpenAPI 规范来描述和定义 API，可以自动生成 API 文档，包括请求和响应参数、错误码、返回值等。
如何在 Deno 中使用 Swagger？
在 Deno 中使用 Swagger 构建 API 文档非常简单。首先，我们需要安装 djwt 和 oak 这两个依赖项：
- ---- ------- ----------- ------------ ----------------------------------- - ---- ------- ----------- ------------ ------------------------------
然后，我们需要创建一个 API 文件。在本文中，我们将创建一个简单的 API，用于登录和验证用户。我们将在 api.ts 文件中定义 API：
------ - ------ - ---- ---------------------------------
------ - -------- -------------- ----- ------- - ---- -------------------------------------
------ - ----------- - ---- ---------------------------------------
----- ------ - --- ---------
----- --- - --------------
--------- ---- -
--------- -------
--------- -------
-
----- ------ ------ - -
-
--------- --------
--------- --------
--
--
----- ------- ---- - -
---- --------
---- ------
--
--------------------- ----- ----- -- -
----- - -------- -------- - - ----
----- ---- - ----- ---------------
----- - --------- -------- - - -----------
----- ---- - ----------------- -- ------------- --- -------- -- ------------- --- ----------
-- ------- -
--------------- - ----
------------- - - -------- -------- -------- -- --------- --
-------
-
----- -------- ------- - -
---- ---------
---- ----------------- ---------------- - -------
--
----- --- - --------- ------- -------- --- ---
------------- - - --- --
---
------------------- ----- ----- -- -
----- - -------- -------- - - ----
----- ------------- - -------------------------------------
-- ---------------- -
--------------- - ----
------------- - - -------- -------------- ------ -- -------- --
-------
-
----- --- - --------------------- ------
----- ------- - ----- ---------------- ---- - ----------- ----- ---
-- ---------- -
--------------- - ----
------------- - - -------- -------- --- ------ --
-------
-
------------- - - -------- ------- --------------- --
---
------ ------- -------在上面的代码中，我们定义了两个路由：/login 和 /user。/login 路由用于登录，验证用户，生成 JWT token，并将 JWT token 返回给客户端。/user 路由用于验证 JWT token，并返回用户信息。
接下来，我们需要安装 Swagger：
- ---- ------- ------------ ----------- ------------- ----------- ---------------------------------------
然后，我们需要在 api.ts 文件中添加 Swagger 注释。Swagger 注释用于描述 API 的请求和响应参数、错误码、返回值等。在本文中，我们将使用 oak 中的 swagger 函数来生成 Swagger 注释。
------ - ------ - ---- ---------------------------------
------ - -------- -------------- ----- ------- - ---- -------------------------------------
------ - ----------- - ---- ---------------------------------------
------ - ------- - ---- ---------------------------------
----- ------ - --- ---------
----- --- - --------------
--------- ---- -
--------- -------
--------- -------
-
----- ------ ------ - -
-
--------- --------
--------- --------
--
--
----- ------- ---- - -
---- --------
---- ------
--
---
- --------
- -------
- -----
- -------- -----
- ------------
- --------
- -----------------
- -------
- ----- ------
- -----------
- ---------
- ----- ------
- ---------
- ----- ------
- ---------
- - --------
- - --------
- ----------
- ----
- ------------ --
- --------
- -----------------
- -------
- ----- ------
- -----------
- ----
- ----- ------
- ----
- ------------ ------------
- --------
- -----------------
- -------
- ----- ------
- -----------
- --------
- ----- ------
--
--------------------- ----- ----- -- -
----- - -------- -------- - - ----
----- ---- - ----- ---------------
----- - --------- -------- - - -----------
----- ---- - ----------------- -- ------------- --- -------- -- ------------- --- ----------
-- ------- -
--------------- - ----
------------- - - -------- -------- -------- -- --------- --
-------
-
----- -------- ------- - -
---- ---------
---- ----------------- ---------------- - -------
--
----- --- - --------- ------- -------- --- ---
------------- - - --- --
---
---
- --------
- ------
- ----
- -------- --- ----
- ---------
- - ----------- --
- ----------
- ----
- ------------ --
- --------
- -----------------
- -------
- ----- ------
- -----------
- --------
- ----- ------
- ----
- ------------ ------------
- --------
- -----------------
- -------
- ----- ------
- -----------
- --------
- ----- ------
--
------------------- ----- ----- -- -
----- - -------- -------- - - ----
----- ------------- - -------------------------------------
-- ---------------- -
--------------- - ----
------------- - - -------- -------------- ------ -- -------- --
-------
-
----- --- - --------------------- ------
----- ------- - ----- ---------------- ---- - ----------- ----- ---
-- ---------- -
--------------- - ----
------------- - - -------- -------- --- ------ --
-------
-
------------- - - -------- ------- --------------- --
---
------ ------- -------------------------在上面的代码中，我们使用 swagger 函数将路由转换为 Swagger 注释，并导出 Swagger 注释。
最后，我们需要运行 API：
- ---- --- ----------- ------------ ------
然后，我们可以在浏览器中打开 http://localhost:8000/swagger-ui 来查看 API 文档。
总结
在本文中，我们介绍了如何在 Deno 中使用 Swagger 构建 API 文档。我们首先安装了依赖项 djwt 和 oak，然后创建了一个简单的 API。接着，我们安装了 Swagger，并在 api.ts 文件中添加了 Swagger 注释。最后，我们运行了 API，并在浏览器中查看了 API 文档。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/65d03487add4f0e0ff93e3d1