{"id":33278690,"url":"https://github.com/alovn/apidocgen","last_synced_at":"2026-03-10T20:35:25.141Z","repository":{"id":38015947,"uuid":"488842279","full_name":"alovn/apidocgen","owner":"alovn","description":"apidocgen is a tool for Go to generate apis markdown docs and mocks.","archived":false,"fork":false,"pushed_at":"2023-06-02T12:59:58.000Z","size":161,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-14T14:16:07.381Z","etag":null,"topics":["apidocgen","apidocs","golang","markdown","mock","mock-server"],"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/alovn.png","metadata":{"files":{"readme":"README-zh.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":"2022-05-05T05:24:32.000Z","updated_at":"2025-03-02T16:47:31.000Z","dependencies_parsed_at":"2024-06-21T02:27:52.051Z","dependency_job_id":null,"html_url":"https://github.com/alovn/apidocgen","commit_stats":null,"previous_names":["alovn/apidoc"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/alovn/apidocgen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alovn%2Fapidocgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alovn%2Fapidocgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alovn%2Fapidocgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alovn%2Fapidocgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alovn","download_url":"https://codeload.github.com/alovn/apidocgen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alovn%2Fapidocgen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30352890,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T15:55:29.454Z","status":"ssl_error","status_checked_at":"2026-03-10T15:54:58.440Z","response_time":106,"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":["apidocgen","apidocs","golang","markdown","mock","mock-server"],"created_at":"2025-11-17T10:00:42.822Z","updated_at":"2026-03-10T20:35:25.115Z","avatar_url":"https://github.com/alovn.png","language":"Go","funding_links":[],"categories":["[](https://github.com/golang/go/wiki/CodeTools#code-generation-templating-and-generics)Code generation, Templating and Generics"],"sub_categories":["[](https://github.com/golang/go/wiki/CodeTools#tools)Tools"],"readme":"# apidocgen\n\n[English](./README.md) | 简体中文\n\napidocgen 是一个为Go项目生成api文档(makrdown格式)和mock的工具。\n\n## 安装\n\n```bash\ngo install github.com/alovn/apidocgen@latest\n```\n\n## 命令\n\n```bash\n$ apidocgen --help\napidocgen is a tool for Go to generate apis markdown docs and mocks. For example:\n\napidocgen --dir= --excludes= --output= --output-index= --template= --single --gen-mocks\napidocgen --mock --mock-listen=:8001\napidocgen mock --data= --listen=\n\nUsage:\n  apidocgen [flags]\n  apidocgen [command]\n\nAvailable Commands:\n  help        Help about any command\n  mock        \n  version     print version\n\nFlags:\n      --dir string            Search apis dir, comma separated (default \".\")\n      --excludes string       Exclude directories and files when searching, comma separated\n      --gen-mocks             Is generate the mock files\n  -h, --help                  help for apidocgen\n      --mock-listen string    Mock Server listen address (default \"localhost:8001\")\n      --mock                  Serve a mock server\n      --output string         Generate markdown files dir (default \"./docs/\")\n      --output-index string   Generate index file name\n      --single                Is generate a single doc\n      --template string       Template name or custom template directory, built-in includes markdown and apidocs\n\nUse \"apidocgen [command] --help\" for more information about a command.\n```\n\n## 模板\n\n模板用于生成文档，内置的模板名称有 `markdown` 和 `apidocs`, 默认是 `markdown`.\n\n其中 `apidocs` 模板是用于 [apidocs](https://github.com/alovn/apidocs) 这个项目中显示的。\n\n也可以使用自己的模板文件:\n\n```bash\napidocgen \\\n    --dir=svc-user,common \\\n    --template=/Users/xxx/workspace/apidocs/custom-template-direcoty \\\n    --output=./docs\n```\n\n## 怎样使用\n\napidocgen 支持Go语言下所有的web框架. 下面是一个 [bytego](https://github.com/gostack-labs/bytego) 框架的示例.\n\n1. 在`main.go`文件中添加注解(注释):\n\n    ```go\n    //@title UserService\n    //@service svc-user\n    //@version 1.0.1\n    //@desc the api about users\n    //@baseurl /user\n    func main() {\n        r := bytego.New()\n        c := controller.NewController()\n        //@group account\n        //@title Account\n        //@desc account register and login\n        account := r.Group(\"/account\")\n        {\n            account.POST(\"/register\", c.Register)\n            account.POST(\"/login\", c.Login)\n        }\n        _ = r.Run(\":8000\")\n    }\n    ```\n\n2. 为API添加注解.\n\n    ```go\n    //@title AccountLogin\n    //@api POST /account/login\n    //@group account\n    //@accept json\n    //@format json\n    //@request LoginRequest\n    //@response 200 common.Response{code=0,msg=\"success\",data=LoginResponse} \"success description\" //mock\n    //@response 200 common.Response{code=10020,msg=\"password_error\"} \"error description\"\n    //@author alovn\n    func (c *Controller) Login(c *bytego.Ctx) {\n        //bind LoginRequest\n        res := common.NewResponse(0, \"success\", \u0026LoginResponse{\n            WelcomeMsg: \"welcome\",\n        })\n        c.JSON(http.StatusOK, res)\n    }\n    ```\n\n3. 执行 `apidocgen`.\n\n    ```bash\n    apidocgen\n    ```\n\n    执行后，markdown格式的文档将默认生成在 `./docs` 目录下.\n\n## 示例\n\n更完整的示例在这里: [apidocgen/examples](https://github.com/alovn/apidocgen/tree/main/examples).\n\n这是一个用`apidocs`模板生成的在线浏览的网站模板示例: [https://apidocgen.netlify.app/](https://apidocgen.netlify.app/)\n\n## 注解(注释)\n\n目前支持的注解有下面这些：\n\nannotation|description|example\n--|--|--\nservice|Required, api服务标识|@service svc-user\nbaseurl|所有api的url前缀|@baseurl /\ngroup|api的分组, 可以添加到api的注释上，或添加到文件头部的注释(该文件中所有的api都会添加到该分组下,api中可省略该注解).|@group account\ntitle|service、group、api的标题|@title UserService\ndesc|service、group、api的详细描述信息|@desc xxx\napi|api的标识|@api POST /account/register\norder|group、api的排序(从小到大)|@order 1\nauthor|api的作者(维护者)|@author alovn\nversion|service、api的版本号|@version 1.0.1\naccept|reuest请求的数据格式, 支持 json、xml|@accept json\nformat|response输出的数据格式, 支持 json/xml|@format json\nrequest|request请求对象|@request LoginRequest\nresponse|response输出对象。 [http code] [data type]|@response 200 LoginResponse\nsuccess|同@response|@success 200 LoginResponse\nfailure|同@response|@failure 200 LoginResponse\nparam|URL中的path路由参数 `/user/:id`。参数由空格分割 [name] [type] [required] [comment],|@param id int true \"user_id\"\nquery|URL中的query请求参数, `/user?id=`,格式同 @param|@query id int true \"user_id\"\nheader|header请求参数, 格式同 @param|@header X-Request-ID string false \"request id\"\nform|The form parameter of request, 格式同 @param|@form id int true \"user_id\"\ndeprecated|标记api过期.|@deprecated\n\n## Response\n\n1. 输出自定义的结构体.\n\n    ```go\n    type User struct {\n        ID int `json:\"id\"`\n        Name string `json:\"name\"`\n    }\n\n    //@response 200 User \"description\"\n    ```\n\n2. 输出结构体的数组.\n\n    ```go\n    //@response 200 []User\n    ```\n\n3. 输出一个结构体，并替换结构体的字段.\n\n    ```go\n    type Response struct {\n        Code int `json:\"code\"`\n        Msg string `json:\"msg\"`\n        Data interface{} `json:\"data\"`\n    }\n\n    //@response 200 Response{code=10001,msg=\"some error\"} \"some error description\"\n    //@response 200 Response{code=0,data=User} \"success description\"\n    //@response 200 Response{code=0,data=[]User} \"success description\"\n    ```\n\n    如果 Response 结构体是在common包中, 就要使用 `common.Response`:\n\n    ```go\n    import (\n        \"common\"\n    )\n\n    //@response 200 common.Response{code=0,data=User} \"success description\"\n    ```\n\n4. 添加example tag, 为结构体输出示例值。\n\n    ```go\n    type User struct {\n        ID int `json:\"id\" example:\"100010\"`\n        Name string `json:\"name\" example:\"user name\"`\n    } //User Infomation\n    ```\n\n## Mock\n\n1. 为api生成mock文件. 在 api 的 `@response` 注解后添加 `//mock` 注释`，如果没有则默认使用第一个.\n\n    ```go\n    //@response 200 Response{code=0,data=[]User} \"success description\" //mock\n    ```\n\n    执行以下命令生成mock数据文件，默认生成的在 `./docs/mocks` 目录下.\n\n    ```bash\n    apidocgen --dir=common,svc-user --gen-mocks\n    ```\n\n2. 使用生成的mock数据，启动一个mock server.\n\n    ```bash\n    apidocgen mock --data=./mocks --listen=:8001\n    ```\n\n3. 也可以不生成mock数据文件，直接启动一个mock server.\n\n    ```bash\n    apidocgen --dir=common,svc-user --mock --mock-listen=:8001\n    ```\n\n4. 测试、使用mock server\n\n    ```bash\n    $ curl -X POST -d \"\" localhost:8001/user/account/login   \n    {\n      \"code\": 0,\n      \"data\": {\n        \"welcome_msg\": \"string\"\n      },\n      \"msg\": \"success\"\n    }\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falovn%2Fapidocgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falovn%2Fapidocgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falovn%2Fapidocgen/lists"}