补全 API OpenAPI 文档 #2

chensipeng · 2026-05-14T18:20:54+08:00

chensipeng commented

2026-05-14 18:20:54 +08:00

变更概述

为 Go HTTP API handler 补充 Swagger/OpenAPI 注释，覆盖健康检查、鉴权、平台/模型、目录、访问规则、身份管理、定价、运行策略、钱包、任务和静态资源接口。
新增文档专用 schema，用实际请求/返回类型补充 OpenAPI 的请求体、返回值和错误响应引用。
生成并提交 apps/api/docs/swagger.json 与 apps/api/docs/swagger.yaml，便于下游工具直接消费。
增加 pnpm openapi 与 pnpm openapi:open 命令，支持生成文档和本地打开 HTML 文档页。
在 README 中提醒修改 apps/api/internal/httpapi 后重新执行 pnpm openapi。

分支范围

该 PR 基于 main 新建 feature/openapi-docs，只包含 OpenAPI 文档相关提交。
已跳过 chore(dev): 配置本地开发环境，不包含 devenv/starship/dev.sh 等开发环境变更。

验证

pnpm openapi：成功生成 swagger.json 与 swagger.yaml。
pnpm openapi:open：成功构建 apps/api/docs/index.html 并打开本地文档页面。
go test ./...（apps/api）：通过。

影响说明

不向 go.mod 增加 swag 运行时依赖，生成命令通过 go run github.com/swaggo/swag/cmd/swag@v1.16.4 临时执行。
OpenAPI 预览使用 pnpm dlx 临时调用 @redocly/cli 构建 HTML 页面。

## 变更概述 - 为 Go HTTP API handler 补充 Swagger/OpenAPI 注释，覆盖健康检查、鉴权、平台/模型、目录、访问规则、身份管理、定价、运行策略、钱包、任务和静态资源接口。 - 新增文档专用 schema，用实际请求/返回类型补充 OpenAPI 的请求体、返回值和错误响应引用。 - 生成并提交 apps/api/docs/swagger.json 与 apps/api/docs/swagger.yaml，便于下游工具直接消费。 - 增加 pnpm openapi 与 pnpm openapi:open 命令，支持生成文档和本地打开 HTML 文档页。 - 在 README 中提醒修改 apps/api/internal/httpapi 后重新执行 pnpm openapi。 ## 分支范围 - 该 PR 基于 main 新建 feature/openapi-docs，只包含 OpenAPI 文档相关提交。 - 已跳过 chore(dev): 配置本地开发环境，不包含 devenv/starship/dev.sh 等开发环境变更。 ## 验证 - pnpm openapi：成功生成 swagger.json 与 swagger.yaml。 - pnpm openapi:open：成功构建 apps/api/docs/index.html 并打开本地文档页面。 - go test ./...（apps/api）：通过。 ## 影响说明 - 不向 go.mod 增加 swag 运行时依赖，生成命令通过 go run github.com/swaggo/swag/cmd/swag@v1.16.4 临时执行。 - OpenAPI 预览使用 pnpm dlx 临时调用 @redocly/cli 构建 HTML 页面。

chensipeng added 1 commit 2026-05-14 18:20:57 +08:00

docs(api): 补全 OpenAPI 注释与生成文档 918dfbfee1

为接口、模型与脚本补齐 Swagger/OpenAPI 注释，生成最新文档，并增加一键生成与查看入口。

chensipeng requested review from wangbo 2026-05-14 18:28:44 +08:00

chensipeng added 1 commit 2026-05-15 09:44:26 +08:00

Merge remote-tracking branch 'origin/main' into feature/openapi-docs 5d3e543cba

# Conflicts:
#	apps/api/internal/httpapi/handlers.go

chensipeng merged commit 7abb6a1baf into main

2026-05-15 09:46:20 +08:00

chensipeng referenced this issue from a commit

2026-05-15 09:46:21 +08:00

Merge pull request '补全 API OpenAPI 文档' (#2) from feature/openapi-docs into main

Sign in to join this conversation.

No reviewers

No Label

No Milestone

No project

No Assignees

1 Participants

Notifications

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: BCAI/easyai-ai-gateway#2