如何在 Deno 中为 API 编写文档？-JavaScript中文网-JavaScript教程资源分享门户

Deno 是一个新兴的 JavaScript/TypeScript 运行时环境。它支持直接执行 JavaScript 和 TypeScript 代码，并且内置了基本的网络库和文件操作 API。对前端开发人员来说，Deno 提供了一种全新的方式来构建 web 应用程序和 API 服务。

本文将介绍如何在 Deno 中为 API 编写文档。文档编写是 API 开发过程中非常重要的一环，它可以帮助其他开发人员了解你提供的 API 服务，减少开发者之间的沟通成本，提高开发效率和可维护性。

使用 Oak 框架和 SwaggerUI

Oak 是一个基于中间件和路由的 web 框架，它允许您轻松地创建 HTTP API。SwaggerUI 是一个流行的 API 文档工具，它允许您为 RESTful API 创建漂亮并且易于理解的文档。

要使用 Oak 和 SwaggerUI，您需要按照下列步骤进行操作：

安装 Oak 和 SwaggerUI

在您的 Deno 项目中使用以下命令安装 Oak 和 SwaggerUI：

import { Application } from "https://deno.land/x/oak/mod.ts";
import { SwaggerUI } from "https://deno.land/x/swagger_ui/mod.ts";

编写 API 接口

使用 Oak 编写您的 API 接口，例如：

// javascriptcn.com 代码示例
// app.ts
import { Application, Router } from "https://deno.land/x/oak/mod.ts";

const router = new Router();

router.get("/", (ctx) => {
  ctx.response.body = "Hello, World!";
});

router.get("/movies", (ctx) => {
  ctx.response.body = [
    { title: "The Godfather", year: 1972 },
    { title: "The Shawshank Redemption", year: 1994 },
  ];
});

const app = new Application();

app.use(router.routes());
app.use(router.allowedMethods());

await app.listen({ port: 8000 });

在上述示例中，我们定义了两个路由，"/" 和 "/movies"。路由 "/" 响应字符串 Hello, World!，路由 "/movies" 响应一个电影数组。

编写 SwaggerUI 基本配置

在您的 Deno 项目中创建一个新文件，例如 swagger.ts。在该文件中，您需要指定以下 SwaggerUI 基本配置：

// javascriptcn.com 代码示例
// swagger.ts
import { swaggerUI } from "https://deno.land/x/swagger_ui/mod.ts";

const swaggerDocument = {
  swagger: "2.0",
  info: {
    title: "Deno API",
    version: "1.0.0",
  },
  host: "localhost:8000",
  basePath: "/",
  schemes: ["http"],
  consumes: ["application/json"],
  produces: ["application/json"],
  paths: {},
  definitions: {},
};

export function getSwaggerMiddleware() {
  return swaggerUI.setup(swaggerDocument);
}

在上述示例中，我们定义了一个 Swagger 文档对象 swaggerDocument，该对象指定了 API 的基本信息，例如标题、版本、主机、基础路径、协议、内容类型和返回类型。动态路由和参数的定义将在后续步骤中完成。

定义 SwaggerUI 路由

在 swagger.ts 中，您需要定义一个 Router，该路由负责呈现 SwaggerUI 页面和 API 文档。您可以使用 Oak 中内置的方式定义路由，例如：

// swagger.ts
const swaggerRouter = new Router();
swaggerRouter.get("/docs", getSwaggerMiddleware());
swaggerRouter.get("/docs/swagger.json", (ctx) => {
  ctx.response.body = swaggerDocument;
});

export default swaggerRouter;

在上述示例中，我们创建了两个路由 "/docs" 和 "/docs/swagger.json"，路由 "/docs" 响应 SwaggerUI 界面，路由 "/docs/swagger.json" 响应 Swagger 文档对象。

挂载 SwaggerUI 路由

回到 app.ts，在引入 Oak 之后，导入 swaggerRouter 并将其挂载到应用程序中：

// javascriptcn.com 代码示例
// app.ts
import { Application, Router } from "https://deno.land/x/oak/mod.ts";
import swaggerRouter from "./swagger.ts";

const router = new Router();

router.get("/", (ctx) => {
  ctx.response.body = "Hello, World!";
});

router.get("/movies", (ctx) => {
  ctx.response.body = [
    { title: "The Godfather", year: 1972 },
    { title: "The Shawshank Redemption", year: 1994 },
  ];
});

const app = new Application();

app.use(router.routes());
app.use(router.allowedMethods());
app.use(swaggerRouter.routes());
app.use(swaggerRouter.allowedMethods());

await app.listen({ port: 8000 });

在上述示例中，我们使用 app.use() 方法将 swaggerRouter 挂载到应用程序中。

定义动态路由和参数

在您的 Deno 项目中，您可以定义多个路由，路由可以带有动态参数。例如：

router.get("/movies/:id", (ctx) => {
  const { id } = ctx.params;
  ctx.response.body = { title: `Movie ${id}`, year: 2000 };
});

在上述示例中，我们定义了一个动态路由 "/movies/:id"，其中 :id 代表一个参数，其值可以在 ctx.params 对象中获得。

SwaggerUI 将自动将这些动态路由和参数集成到 API 文档中。

运行应用程序并查看文档

使用以下命令在 Deno 中运行应用程序：

deno run --allow-net app.ts

在浏览器中访问 http://localhost:8000/docs，您应该可以看到 API 文档和 SwaggerUI 界面。

至此，我们就完成了在 Deno 中为 API 编写文档的过程。SwaggeUI 让我们能够更加容易地创建和维护 API 文档，提高了可维护性和可读性，是开发 API 接口的必备工具之一。

总结

本文介绍了如何在 Deno 中为 API 编写文档。我们使用了 Oak 和 SwaggerUI 工具，通过定义基本文档配置、路由、参数和动态路由，编写了一份漂亮且易于理解的 API 文档。希望这篇文章能够给你带来启示，并帮助您更好地开发和维护 Deno 项目。

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/6542f9cd7d4982a6ebca06ea