使用 sveltekit-api-gen 自动化您的 API 文档

Source: Dev.to

Introduction

文档往往是开发中被忽视的部分。我们都知道应该编写文档，但让 OpenAPI 规范与代码保持同步可能会很繁琐。
如果你正在使用 SvelteKit 构建后端，sveltekit-api-gen 可以帮你解决这个问题。

核心思路很简单：把你的端点实现文件当作唯一真实来源，然后从中生成其他所有内容。

How It Works

sveltekit-api-gen 通过直接解析代码中的 JSDoc @swagger 注解，自动从你的 SvelteKit 服务器端点生成 OpenAPI 3.0 规范。你不需要维护单独的 YAML 或 JSON 文件，只需在实现文件中添加注解即可。

Example

// src/routes/api/users/+server.ts

/**
 * @swagger
 * /api/users:
 *   get:
 *     description: Get all users
 *     responses:
 *       200:
 *         description: A list of users
 */
export async function GET() {
  // ... your logic
}

sveltekit-api-gen 会扫描这些注释，为你构建完整、符合规范的 OpenAPI 文档。

Lightweight Workflow

1. Add @swagger docs 在构建端点时添加 @swagger 文档。
2. Generate 在 CI 中生成 openapi.json（或 openapi.yaml）。
3. Publish 将其发布到 Swagger UI、Postman 或内部文档站点。
4. Fail CI 如果生成出错，立即捕获文档漂移并使 CI 失败。

Benefits

• Single Source of Truth – 文档就位于代码旁边。更新注释即更新规范。
• Automation – 再也不需要手动更新庞大的 JSON 文件。
• Standard Compliant – 生成兼容 Swagger UI、Postman 等工具的 OpenAPI 3.0 规范。

Best Practices

• Be consistent with paths – 确保文档中的路径与 SvelteKit 路由布局保持一致。
• Document error responses – 即使是简单的 400 与 500 响应也能节省调试时间。
• Keep schemas close – 如果你使用 Zod 或类似库，考虑在 Swagger 文档中镜像重要的约束。

Installation

npm install -D sveltekit-openapi-generator
# or
pnpm add -D sveltekit-openapi-generator
# or
bun add -d sveltekit-openapi-generator

安装完成后，查看仓库的 README，了解具体的生成命令和你想要的输出路径（该工具可高度配置）。

Repository

https://github.com/Michael-Obele/sveltekit-api-gen

如果你觉得这篇文章有帮助，请给仓库点个星！