{"id":24861692,"url":"https://github.com/pubgo/opendoc","last_synced_at":"2026-05-15T01:12:11.501Z","repository":{"id":192571593,"uuid":"660958541","full_name":"pubgo/opendoc","owner":"pubgo","description":"Simple and easy-to-use toolkit for building openapi","archived":false,"fork":false,"pushed_at":"2024-04-29T13:38:02.000Z","size":563,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-31T22:19:30.813Z","etag":null,"topics":["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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pubgo.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":"security/aaa.go","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-01T10:42:22.000Z","updated_at":"2024-07-29T13:48:56.000Z","dependencies_parsed_at":"2023-09-05T03:03:37.838Z","dependency_job_id":"f0c27f24-1c7b-4e8d-be1b-5835e766d844","html_url":"https://github.com/pubgo/opendoc","commit_stats":null,"previous_names":["pubgo/opendoc"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pubgo%2Fopendoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pubgo%2Fopendoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pubgo%2Fopendoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pubgo%2Fopendoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pubgo","download_url":"https://codeload.github.com/pubgo/opendoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245699289,"owners_count":20657987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["openapi","openapi3"],"created_at":"2025-01-31T22:19:05.364Z","updated_at":"2026-05-15T01:12:11.488Z","avatar_url":"https://github.com/pubgo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenDoc - Go OpenAPI 文档生成工具\n\n## 简介\n\n`OpenDoc` 是一个用于 Go 项目的 OpenAPI 文档生成工具，它能够自动生成符合 OpenAPI 3.0 规范的 API 文档，并提供请求模型验证功能。该项目与具体 HTTP 框架无关，可以与任何 HTTP 框架（Gin、Echo、Fiber 等）一起使用，提供了一套完整的 API 文档解决方案。\n\n## 特性\n\n- 自动生成 OpenAPI 3.0 规范的 API 文档\n- 支持多种安全认证方式（Basic、Bearer、ApiKey、OpenID、OAuth2）\n- 请求参数自动验证和模型映射\n- 支持服务分组和路由管理\n- 提供 Swagger UI、Redoc 和 RapiDoc 文档展示\n- 支持子应用挂载和独立文档\n- 可在生产环境中禁用文档功能\n- 与 HTTP 框架无关，可集成到任何 Go HTTP 项目\n- 提供丰富的 API 访问方法，便于程序化操作\n\n## 安装\n\n```shell\ngo get -u github.com/pubgo/opendoc\n```\n\n## 快速开始\n\n以下是一个简单的使用示例：\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\n\t\"github.com/samber/lo\"\n\n\t\"github.com/pubgo/opendoc/opendoc\"\n\t\"github.com/pubgo/opendoc/security\"\n\t\"github.com/pubgo/opendoc/templates\"\n)\n\ntype TestQueryReq struct {\n\tID       int     `path:\"id\" validate:\"required\" json:\"id\" description:\"id of model\" default:\"1\"`\n\tName     string  `required:\"true\" json:\"name\" validate:\"required\" doc:\"name of model\" default:\"test\"`\n\tName1    *string `required:\"true\" json:\"name1\" validate:\"required\" doc:\"name1 of model\" default:\"test\"`\n\tToken    string  `header:\"token\" json:\"token\" default:\"test\"`\n\tOptional string  `query:\"optional\" json:\"optional\"`\n}\n\ntype TestQueryRsp struct {\n\tCode int    `json:\"code\"`\n\tMsg  string `json:\"msg\"`\n\tData any    `json:\"data\"`\n}\n\nfunc main() {\n\tdoc := opendoc.New(func(swag *opendoc.Swagger) {\n\t\tswag.Title = \"this service web title \"\n\t\tswag.Description = \"this is description\"\n\t\tswag.Version = \"1.0.0\"\n\t\tswag.License = \u0026opendoc.License{\n\t\t\tName: \"Apache License 2.0\",\n\t\t\tURL:  \"https://github.com/pubgo/opendoc/blob/master/LICENSE\",\n\t\t}\n\n\t\tswag.Contact = \u0026opendoc.Contact{\n\t\t\tName:  \"barry\",\n\t\t\tURL:   \"https://github.com/pubgo/opendoc\",\n\t\t\tEmail: \"kooksee@163.com\",\n\t\t}\n\n\t\tswag.TermsOfService = \"https://github.com/pubgo\"\n\t})\n\n\tdoc.ServiceOf(\"test article service\", func(srv *opendoc.Service) {\n\t\tsrv.SetPrefix(\"/api/v1\")\n\t\tsrv.AddSecurity(security.Basic{}, security.Bearer{})\n\t\tsrv.PostOf(func(op *opendoc.Operation) {\n\t\t\top.SetPath(\"/articles\")\n\t\t\top.SetOperation(\"article_create\")\n\t\t\top.SetModel(new(TestQueryReq), new(TestQueryRsp))\n\t\t\top.SetSummary(\"create article\")\n\t\t\top.SetDescription(\"Creates a new article with the provided data\")\n\t\t})\n\n\t\tsrv.GetOf(func(op *opendoc.Operation) {\n\t\t\top.SetPath(\"/articles\")\n\t\t\top.SetOperation(\"article_list\")\n\t\t\top.SetModel(new(TestQueryReq), new(TestQueryRsp))\n\t\t\top.SetSummary(\"get article list\")\n\t\t\top.SetDescription(\"Retrieves a list of articles\")\n\t\t})\n\n\t\tsrv.PutOf(func(op *opendoc.Operation) {\n\t\t\top.SetPath(\"/articles/{id}\")\n\t\t\top.SetOperation(\"article_update\")\n\t\t\top.SetModel(new(TestQueryReq), new(TestQueryRsp))\n\t\t\top.SetSummary(\"update article\")\n\t\t\top.SetDescription(\"Updates an existing article by ID\")\n\t\t})\n\n\t\tsrv.DeleteOf(func(op *opendoc.Operation) {\n\t\t\top.SetPath(\"/articles/{id}\")\n\t\t\top.SetOperation(\"article_delete\")\n\t\t\top.SetModel(new(TestQueryReq), new(TestQueryRsp))\n\t\t\top.SetSummary(\"delete article\")\n\t\t\top.SetDescription(\"Deletes an article by ID\")\n\t\t})\n\t})\n\n\thttp.HandleFunc(\"/docs/\", templates.SwaggerHandler(\"API Documentation\", \"/openapi.json\"))\n\thttp.HandleFunc(\"/redoc/\", templates.ReDocHandler(\"API Documentation\", \"/openapi.json\"))\n\thttp.HandleFunc(\"/rapidoc/\", templates.RApiDocHandler(\"/openapi.json\"))\n\thttp.HandleFunc(\"/openapi.json\", func(w http.ResponseWriter, r *http.Request) {\n\t\tswagger := doc.BuildSwagger()\n\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\tdata, _ := swagger.MarshalJSON()\n\t\tw.Write(data)\n\t})\n\n\tfmt.Println(\"Server starting at :8080\")\n\tfmt.Println(\"Visit http://localhost:8080/docs/ for API documentation\")\n\tif err := http.ListenAndServe(\":8080\", nil); err != nil {\n\t\tpanic(err)\n\t}\n}\n```\n\n## 核心概念\n\n### Swagger 配置\n\n使用 `opendoc.New()` 创建 Swagger 实例，可以配置项目的基本信息：\n\n```go\ndoc := opendoc.New(func(swag *opendoc.Swagger) {\n    swag.Title = \"API Title\"\n    swag.Description = \"API Description\"\n    swag.Version = \"1.0.0\"\n    swag.License = \u0026opendoc.License{\n        Name: \"Apache License 2.0\",\n        URL:  \"https://license-url\"\n    }\n    swag.Contact = \u0026opendoc.Contact{\n        Name:  \"Contact Name\",\n        URL:   \"https://contact-url\",\n        Email: \"contact@example.com\"\n    }\n})\n```\n\n### 服务定义\n\n使用 `ServiceOf` 方法定义服务组：\n\n```go\ndoc.ServiceOf(\"service-name\", func(srv *opendoc.Service) {\n    srv.SetPrefix(\"/api/v1\")  // 设置路由前缀\n    srv.AddTags(\"User\", \"Account\")  // 添加标签\n    srv.AddSecurity(security.Basic{})  // 添加安全认证\n})\n```\n\n### 操作定义\n\n在服务中定义 API 操作：\n\n```go\nsrv.GetOf(func(op *opendoc.Operation) {\n    op.SetPath(\"/users\")\n    op.SetOperation(\"get_users\")\n    op.SetModel(requestStruct, responseStruct)\n    op.SetSummary(\"获取用户列表\")\n    op.SetDescription(\"获取所有用户信息\")\n})\n```\n\n### 安全认证\n\nOpenDoc 支持多种安全认证方式：\n\n- `security.Basic{}` - HTTP Basic 认证\n- `security.Bearer{}` - Bearer Token 认证\n- `security.ApiKey{}` - API Key 认证\n- `security.OpenID{}` - OpenID Connect 认证\n- `security.OAuth2{}` - OAuth2 认证\n\n```go\nsrv.AddSecurity(security.Basic{}, security.Bearer{})\n```\n\n## 参数映射\n\nOpenDoc 支持多种参数映射方式：\n\n- `path` - 路径参数\n- `query` - 查询参数\n- `header` - 请求头参数\n- `cookie` - Cookie 参数\n- `json` - JSON 请求体参数\n\n```go\ntype RequestStruct struct {\n    ID     int    `path:\"id\" validate:\"required\" json:\"id\"`\n    Name   string `query:\"name\" validate:\"required\" json:\"name\"`\n    Token  string `header:\"authorization\" json:\"token\"`\n    Locale string `cookie:\"locale\" json:\"locale\"`\n}\n```\n\n## 便捷方法\n\nOpenDoc 提供了丰富的便捷方法来访问和操作 API 对象：\n\n### Swagger 对象方法\n- `BuildSwagger()` - 构建 OpenAPI 3.0 规范对象\n- `MarshalJSON()` - 序列化为 JSON\n- `MarshalYAML()` - 序列化为 YAML\n\n### Service 对象方法\n- `GetOperations()` - 获取服务中的所有操作\n- `GetPath()` - 获取服务路径前缀\n- `GetName()` - 获取服务名称\n\n### Operation 对象方法\n- `GetPath()` - 获取操作路径\n- `GetMethod()` - 获取 HTTP 方法\n- `GetOperationID()` - 获取操作 ID\n- `GetSummary()` - 获取摘要\n- `GetDescription()` - 获取描述\n- `GetTags()` - 获取标签列表\n\n## 与其他 HTTP 框架集成\n\nOpenDoc 与 HTTP 框架无关，可以轻松集成到任何 Go HTTP 框架中，如 Gin、Echo、Fiber 等。只需将 OpenDoc 生成的 OpenAPI 规范提供给相应的 HTTP 框架即可。\n\n## 文档模板\n\nOpenDoc 提供了多种文档展示模板：\n\n- Swagger UI - 标准的 Swagger 文档界面\n- Redoc - 现代化的 API 文档界面\n- RapiDoc - 快速、轻量级的文档界面\n\n## 构建和运行\n\n使用以下命令运行示例：\n\n```bash\nmake run-example\n```\n\n或者直接运行：\n\n```bash\ngo run internal/examples/*.go\n```\n\n## 许可证\n\n该项目根据 [Apache-2.0](https://github.com/pubgo/opendoc/blob/master/LICENSE) 许可证授权。","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpubgo%2Fopendoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpubgo%2Fopendoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpubgo%2Fopendoc/lists"}