从头开始创建一个自动产生文档/类型安全的现代API(5) 文档生成

添加Doc支持

添加 app/api/[[...route]]/lab/configure-openapi.ts:

import type { AppOpenAPI } from "@/utility/types";
import packageJSON from "@/package.json" with { type: "json" };

export default function configureOpenAPI(app : AppOpenAPI){
    app.doc("/doc", {
        openapi: "3.0.0",
        info: {
            version: packageJSON.version,
            title: "Tasks API",
        },
    });
}

修改 app/api/[[...route]]/route.ts,添加调用:

...
import configureOpenAPI from './lab/configure-openapi';

const app = createApp();

configureOpenAPI(app);
...

访问 网址 localhost:3001/api/doc,显示如下：

添加路径内容

首先改造 app/api/[[...route]]/lib/create-app.ts, 添加 createRouter():

...
export function createRouter() {
    return new OpenAPIHono<AppBindings>({
        strict: false,
    });
};
...

添加文件 app/api/[[...route]]/routes/index.route.ts， 定义了对/节点访问的信息，同时定义了相应内容和注释：

import { createRoute } from "@hono/zod-openapi";
import * as HttpStatusCodes from "stoker/http-status-codes";
import { jsonContent } from "stoker/openapi/helpers";
import { createMessageObjectSchema } from "stoker/openapi/schemas";

import { createRouter } from "../lib/create-app";

const router = createRouter()
  .openapi(
    createRoute({
      tags: ["Index"],
      method: "get",
      path: "/",
      responses: {
        [HttpStatusCodes.OK]: jsonContent(
          createMessageObjectSchema("Tasks API"),
          "OpenAPI Demo API Index",
        ),
      },
    }),
    (c) => {
      return c.json({
        message: "OpenAPI Demo API",
      }, HttpStatusCodes.OK);
    },
  );

export default router;

同时修改 app/api/[[...route]]/route.ts,添加路径：

import { handle } from 'hono/vercel';

import createApp from "./lib/create-app";
import configureOpenAPI from './lib/configure-openapi';
import index from "./routes/index.route";
const app = createApp();

configureOpenAPI(app);

const routes = [
  index,
] as const;

routes.forEach((route) => {
  app.route("/", route);
});


export const GET = handle(app);

这时我们访问 localhost:3001/api/doc ,显示如下：

让API文档显示更友好

以上显示还不够友好，我们来安装一个工具：scalar 是一个功能强大、易于使用的API客户端和文档生成工具，适用于各种规模的API项目，支持多种编程语言和平台。

安装scalar

bun add @scalar/nextjs-api-reference

添加页面

添加文件 app/reference/route.js:

import { ApiReference } from '@scalar/nextjs-api-reference';

const config = {
  spec: {
    url: '/api/doc',
  },
};

export const GET = ApiReference(config);

这时我们访问 localhost:3001/reference ,显示如下：

切换主题和布局

还可以根据喜好切换主题和布局，修改文件 app/reference/route.js:

import { ApiReference } from '@scalar/nextjs-api-reference';

const config = {
  theme: "kepler",
  layout: "classic",
  defaultHttpClient: {
    targetKey: "js",
    clientKey: "fetch",
  },
  spec: {
    url: '/api/doc',
  },
};

export const GET = ApiReference(config);

以下是效果：

作者：Bearalise
出处：从头开始创建一个自动产生文档/类型安全的现代API(5) 文档生成
版权：本文版权归作者所有
转载：欢迎转载，但未经作者同意，必须保留此段声明，必须在文章中给出原文链接。