{"id":19860631,"url":"https://github.com/goodluckxu-go/openapi","last_synced_at":"2026-02-04T17:05:18.891Z","repository":{"id":221128940,"uuid":"753528268","full_name":"goodluckxu-go/openapi","owner":"goodluckxu-go","description":"使用ast语法解析器解析注解，根据openapi3语法生成","archived":false,"fork":false,"pushed_at":"2025-05-22T08:53:22.000Z","size":221,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-28T05:34:55.557Z","etag":null,"topics":["apigen","openapi","openapi3"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goodluckxu-go.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-06T09:55:54.000Z","updated_at":"2025-05-22T08:51:01.000Z","dependencies_parsed_at":"2024-02-06T10:51:08.140Z","dependency_job_id":"9a35d354-d351-4103-bd56-ed8f5cd3a7de","html_url":"https://github.com/goodluckxu-go/openapi","commit_stats":null,"previous_names":["goodluckxu-go/openapi"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/goodluckxu-go/openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodluckxu-go%2Fopenapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodluckxu-go%2Fopenapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodluckxu-go%2Fopenapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodluckxu-go%2Fopenapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goodluckxu-go","download_url":"https://codeload.github.com/goodluckxu-go/openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodluckxu-go%2Fopenapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29091317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apigen","openapi","openapi3"],"created_at":"2024-11-12T15:06:31.444Z","updated_at":"2026-02-04T17:05:18.872Z","avatar_url":"https://github.com/goodluckxu-go.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# openapi3 文档生成\n\n使用ast语法解析器解析注解，根据openapi3语法生成\n\n## 引用(quote)\n- github.com/getkin/kin-openapi\n\n\n## 用法(usage)\n多行注释可以使用 |- 符号，和@标题一行，不能有其他内容，知道遇到下一个可用标签或者单独一行为-|。例如：\n~~~go\n// @info.title: |-\n//   这是标题\n// @info.description: |-\n//   这是描述\n//  -|\n// 这里的注释是无效的，上面已经终止，如果不些终止符号则为上面标签的注释\n// @info.version: 这是版本号\n~~~\n\n### 安装命令\n~~~shell\ngo install github.com/goodluckxu-go/openapi/cmd/apigen@latest\n~~~\n\n### docs.go文档注释说明\n~~~go\n// @info.title: 标题\n// @info.description: 描述\n// @info.termsOfService: 服务条款\n// @info.contact.name: 联系人\n// @info.contact.url: 联系地址\n// @info.contact.email: 联系邮箱\n// @info.license.name: 许可证名称\n// @info.license.url: 许可证地址\n// @info.version: 项目版本号\n// @externalDocs.description: 扩展文档描述\n// @externalDocs.url: 扩展文档地址\n// @servers: url=服务地址; description=服务描述\n// @tags: name=标签名称; description=标签描述\n// @components.securitySchemes: |-\n//  field=验证字段，路由注释中使用;\n//  type=验证类型，值包括apiKey,http,oauth2;\n//  scheme=http类型必传，例如basic,bearer;\n//  bearerFormat=scheme为bearer时可传，用于提示客户端所使用的bearer token的格式，例如JWT;\n//  in=apiKey时必传，值包括query,header,cookie;\n//  name=apiKey时必传，用于 header、 query 或 cookie 的参数名字;\n//  flows=json字符串，文档说明详见：https://openapi.apifox.cn/#oauth-flows-%E5%AF%B9%E8%B1%A1\npackage main\n~~~\n\n#### docs.go 文档中定义公共的 route.go 中的属性，和 route.go 的注释一致，在@后面添加global.\n- @global.res  公共返回，和路由的一致\n- @global.param  公共参数，和路由的一致\n~~~go\n// @global.res: status=500; in=application/json; content=服务器链接失败; desc=系统内部错误\npackage main\n~~~\n\n### route.go文档注释说明\n- @开始的标题，用 ; 分割，分割成对象。每个对象用 = 分割，分割成键，值，如果不存在 = 好则表示值是字符串 true\n\n- 上面分割的对象中的值，用 , 分割成数组\n~~~go\npackage main\n\n// @summary: 路由总结\n// @description: 路由描述\n// @tags: 标签组，用;分割，例如：user;admin\n// @param: 参数，多行则多个参数，详细说明见下面@param说明\n// @body: 传递内容，详细说明见下面@body说明\n// @res: 输出内容，详解说明见下面@res说明\n// @security: |-\n//  验证值，使用 @components.securitySchemes 中定义的 field 的值\n//  例如：token;projectID=write:pets,read:pets 表示 存在token验证，projectID验证数组是[write:pets,read:pets]\n// @router: |-\n//  method=get,put ,post,delete,options,head,patch中的值;\n//  path=路由地址，例如：/user/{id}。其中{id}表示@param中的in为path时的关联\nfunc Login() {\n}\n~~~\n#### @param说明\n实例：@param: in=path; name=id; type=integer(int64); required; desc=主键\n- in 表示参数类型，值有query,header,path,cookie\n- name 表示参数名称\n- type 表示参数类型，值有integer,number,string,boolean\n- required 是否必传参数，实例：required 或者 required=true\n- desc 参数描述\n- minimum type类型是integer时的最小值\n- maximum type类型是integer时的最大值\n- minLength type类型是string时的最小长度\n- maxLength type类型是string时的最大长度\n- example 实例值\n- default 默认值\n- enum 参数枚举，数组，用,分割，例如：enum=user,name\n#### @body说明\n实例：@body: in=application/json; content=test/project/app/reqs.LoginAdminReq; desc=用户信息\n- in 传入类型，值有 application/json, application/xml, application/x-www-form-urlencoded\n- content 传入内容，以.分割，前缀为go.mod查找的命名空间名称(支持github等，必须引入)，后缀为结构体名称。前缀可以是结构体package的名称，这种情况必须不能重复\n- desc 传入内容描述\n#### @res说明\n实例：@res: status=200; in=application/json; content=test/project/app/resps.AdminLoginResp; desc=返回信息\n- status integer类型，服务器的状态码\n- in 返回类型，值有 application/json, application/xml\n- content 返回内容，以.分割，前缀为go.mod查找的命名空间名称(支持github等，必须引入)，后缀为结构体名称。前缀可以是结构体package的名称，这种情况必须不能重复\n- desc 返回内容描述\n\n### 结构体注释说明\n~~~go\npackage main\n\n// LoginRequest 结构体注释\ntype LoginRequest struct {\n    Account string `json:\"account\" yaml:\"account\" required:\"true\" minimum:\"10\"` // 账号注释\n\tPassword string `json:\"password\" yaml:\"password\" openapi:\"required;minimum=10\"` // 密码注释\n}\n~~~\n\n#### 结构体的标签可以使用 minimum:\"10\" 和 openapi:\"minimum=10\" 这两种方式，字段有\n- minimum type类型是integer时的最小值\n- maximum type类型是integer时的最大值\n- minLength type类型是string时的最小长度\n- maxLength type类型是string时的最大长度\n- minItems type类型是slice时的最小长度\n- maxItems type类型是slice时的最大长度\n- example 实例值\n- default 默认值\n- enum 限定值\n- required 是否必传参数\n- type 类型重定义\n\n## 文件上传\n只需要将in设置为 multipart/form-data， 类型设置为 base64 或者 binary 即可\n\n## 关于(about)\n灵感为 github.com/swaggo/swag 的项目，因为这个项目无法解析 openapi3 的文档，因此自己实现了一套 openapi3 的文档生成","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodluckxu-go%2Fopenapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoodluckxu-go%2Fopenapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodluckxu-go%2Fopenapi/lists"}