GoFrame项目需启用OpenAPI服务模块以支持/swagger和/api.json访问:一、在config.yaml的server节点下配置openapiPath和swaggerPath;二、路由须显式注册且handler上方紧贴// @Summary注释;三、启动后验证/swagger页面加载及/api.json内容有效性。

GoFrame项目需要在浏览器中直接访问/swagger查看交互式接口文档,同时让前端能通过/api.json拿到标准OpenAPI格式的JSON文件用于SDK生成,必须正确启用并配置框架内置的OpenAPI服务模块。
启用OpenAPI服务模块
打开项目根目录下的manifest/config.yaml文件,在server节点下添加openapiPath和swaggerPath两项配置:
server:
address: ":8000"
openapiPath: "/api.json"
swaggerPath: "/swagger"
这两项是硬性开关:缺少openapiPath会导致/api.json 404;缺少swaggerPath则Swagger UI页面无法加载。路径值可自定义,但必须以/开头且不能带查询参数。
确保路由已注册且含有效注释
GoFrame的OpenAPI文档依赖运行时反射+注释提取,不是静态扫描,因此必须满足两个前提:
① 所有HTTP路由必须通过g.Server().BindHandler()或g.Server().Group().GET/POST()等方法显式注册;
② 每个handler函数上方必须紧贴着写// @Summary,中间不能有空行——这是OpenAPI生成器识别接口的唯一锚点。
一款AI工具,主要用于Monitor and clean up invalid Codex authentication files in CPA. Check quota status, disable files returning 401 errors, and perform dual verification before deletion.,适合需要提升相关任务效率的用户。
示例正确写法:
// @Summary 获取用户列表
// @Description 根据分页参数返回用户数据
func (c *UserController) List(r *ghttp.Request) { ... }
如果只写了// @Description而漏掉@Summary,该接口将完全不出现在/api.json的paths字段中,且无任何报错提示。
启动服务并验证输出
执行gf run main.go启动服务。
访问http://127.0.0.1:8000/swagger → 页面正常加载即表示Swagger UI服务就绪;
访问http://127.0.0.1:8000/api.json → 返回完整OpenAPI 3.0.1 JSON对象,且paths非空、info.title为项目名,说明OpenAPI契约已成功导出。
注意:【/api.json内容是运行时动态生成的,不依赖swag init或任何外部工具】,只要服务在跑、路由注册成功、注释合规,JSON就实时可用。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!










