{"id":17684358,"url":"https://github.com/gotomicro/eapi","last_synced_at":"2025-10-18T16:31:52.788Z","repository":{"id":60347713,"uuid":"542521036","full_name":"gotomicro/eapi","owner":"gotomicro","description":"一个通过分析 AST 生成 Swagger 文档的工具","archived":false,"fork":false,"pushed_at":"2025-04-10T08:21:55.000Z","size":897,"stargazers_count":30,"open_issues_count":2,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-10T09:38:14.008Z","etag":null,"topics":["docs","gin","openapi","swagger"],"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/gotomicro.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":"2022-09-28T09:56:33.000Z","updated_at":"2025-04-10T08:21:59.000Z","dependencies_parsed_at":"2024-06-20T01:38:24.925Z","dependency_job_id":"25336306-3a6b-4c3e-8b87-8257783e27e8","html_url":"https://github.com/gotomicro/eapi","commit_stats":null,"previous_names":["gotomicro/ego-gen-api"],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gotomicro%2Feapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gotomicro%2Feapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gotomicro%2Feapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gotomicro%2Feapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gotomicro","download_url":"https://codeload.github.com/gotomicro/eapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253747268,"owners_count":21957731,"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":["docs","gin","openapi","swagger"],"created_at":"2024-10-24T10:05:08.033Z","updated_at":"2025-10-18T16:31:52.702Z","avatar_url":"https://github.com/gotomicro.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"144px\" src=\"docs/logo.png\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eeAPI\u003c/h1\u003e\n\u003cp align=\"center\"\u003e一个通过分析代码生成 OpenAPI 文档的工具\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n   \u003ca href=\"https://goreportcard.com/report/github.com/gotomicro/eapi\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/gotomicro/eapi\" /\u003e\u003c/a\u003e\n   \u003ca href=\"https://github.com/gotomicro/eapi/actions/workflows/go.yml\"\u003e\u003cimg src=\"https://github.com/gotomicro/eapi/workflows/Go/badge.svg?branch=main\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## 介绍\n\neAPI 通过分析 AST 生成 **接口文档** 及 **前端代码**。与 swaggo/swag 等工具不同之处在于，eAPI 无需编写注解即可使用。另外，eAPI 还支持生成 Typescript 类型代码 和 前端接口请求代码。\n\neAPI 首先解析出代码中的路由（方法/路径）声明，得到接口的 Path、Method 及对应的 Handler 函数。然后再对 Handler 函数进行解析，得到 请求参数（Query/FormData/JSON-Payload等）、响应数据等信息。最终生成一份符合 OpenAPI 3 标准的 JSON 文档。\n\neAPI 目前支持了 gin, echo 框架的文档生成，其他主流框架在计划中。如果你需要将 eAPI 应用在其他未被支持的框架，可以通过编写自定义插件的方式进行实现，或者给我们提交 PR。\n\n## 安装\n\n```shell\ngo install github.com/gotomicro/eapi/cmd/eapi@latest\n```\n\n## 如何使用\n1. 创建配置文件\n\n在代码根目录创建配置文件 `eapi.yaml`: \n```yaml\nplugin: gin # 目前支持 gin 和 echo\noutput: docs\ndir: .\n```\n\n2. 生成文档\n\n在代码根目录执行命令: \n```shell\n$ eapi\n```\n\n执行完成后会在 `docs` 目录下生成 `openapi.json` 文件。\n\n[完整的配置说明](#配置)\n\n## 配置\n\n如下是完整的配置文件示例:\n\n```yaml\noutput: docs # 输出文档的目录\nplugin: gin # gin | echo . 取决于你使用的框架，目前支持了 gin 和 echo\ndir: '.' # 需要解析的代码目录\n\n# 可选. 请求/响应数据中依赖的类型对应的包\ndepends:\n - github.com/gotomicro/gotoant\n - gorm.io/datatypes\n\n# 可选. 插件配置. 用于自定义请求响应的函数调用\nproperties:\n  # 自定义请求参数绑定\n  request:\n    - type: '*server/pkg/handler.CustomContext'\n      method: 'Bind'\n      return:\n        data:\n          type: 'args[0]' # 指定第一个函数参数为请求参数\n  # 自定义响应函数\n  response:\n    - type: '*server/pkg/handler.CustomContext'\n      method: 'JSONOK'\n      return:\n        contentType: 'application/json'  # 指定响应的 content-type\n        data: # 这是一个嵌套的数据格式示例 '{\"code\":0,\"msg\":\"hello\",data:{...}}'\n          type: 'object'\n          properties:\n            code:\n              type: 'number'\n            msg:\n              type: 'string'\n            data:\n              optional: true # 是否可选. 默认 false\n              type: 'args[0]' # 指定为第一个函数参数\n        status: 200 # 指定为 200 状态码\n\n# 可选. 配置代码生成器\ngenerators:\n  - name: ts # 生成器名称. 暂时只支持 \"ts\" (用于生成 typescript 类型)\n    output: ./src/types # 输出文件的目录. 执行完成之后会在该目录下生成TS类型文件\n```\n\n### Properties\n`properties` 用于配置自定义请求参数绑定函数和响应输出函数。\n\n#### 自定义请求参数绑定函数\n\n配置示例：\n```yaml\nproperties:\n  # 自定义请求参数绑定\n  request:\n    - type: '*server/pkg/handler.CustomContext'\n      method: 'Bind'\n      return:\n        data:\n          type: 'args[0]' # 指定第一个函数参数为请求参数\n```\n\n#### 自定义响应输出函数\n\n配置示例：\n```yaml\nresponse:\n    - type: '*server/pkg/handler.CustomContext' # 方法所在的 package/receiver\n      method: 'JSONOK'\n      return:\n        contentType: 'application/json'  # 指定响应的 content-type\n        data: # 这是一个嵌套的数据格式示例 '{\"code\":0,\"msg\":\"hello\",data:{...}}'\n          type: 'object'\n          properties:\n            code:\n              type: 'number'\n            msg:\n              type: 'string'\n            data:\n              optional: true # 是否可选. 默认 false\n              type: 'args[0]' # 指定为第一个函数参数\n        status: 200 # 指定为 200 状态码\n```\n\n其中，data type 可选值为：\n- string\n- number\n- integer\n- boolean\n- array\n- file\n- object\n\n此外，还可以将函数入参作为参数类型，eAPI 会自动解析对应的参数类型。比如 `args[0]` 代表函数第一个参数。\n\n完整的配置参考 https://github.com/link-duan/eapi/blob/main/plugins/common/config.go 下面的 `DataSchema` 类型声明。\n\n### 代码生成器配置\n\n如果需要使用代码生成功能，需要在配置文件内添加如下配置:\n```yaml\n# 可选\ngenerators:\n  - name: ts # 生成器名称. 暂时支持 \"ts\" | \"umi\" \n    output: ./src/types # 输出文件的目录. 执行完成之后会在该目录下生成TS类型文件\n```\n\n#### umi-request 请求代码生成\n   \n   umi 代码生成器用于生成适用于使用 `umi.js` 框架的前端接口请求代码及 TypeScript 类型。\n   示例配置：\n   ```yaml\n   generators:\n     - name: umi\n       output: ./src/requests # 输出文件的目录\n   ```\n  \n#### Typescript 类型生成\n\n   ts 代码生成器用于生成 TypeScript 类型代码。\n   示例配置：\n   ```yaml\n   generators:\n     - name: ts\n       output: ./src/types # 输出文件的目录\n   ```\n\n## 注解\n\n如果你需要对文档的内容进行更精细化的调整（比如接口标题、字段是否必选等），那么你需要使用到注解。\n\n### 默认情况\n\n如果没有写注解，eAPI 也会帮你生成关于接口的必要信息。对应关系如下：\n\n| 接口信息   | 默认值  |\n|  :-   |   :-   |\n| 接口的 summary (标题)  |  `pkg.HandlerName` handler 函数所在的包名和函数名共同组成接口标题。如果有注释，会默认使用注释作为标题 |\n| 接口描述 | handler 函数的注释（非注解部分） |\n| Path/Query/Form参数 | 根据代码生成。比如 gin 里面的 `ctx.Query(\"q\")` 会被解析为 query 参数 q 。如果在这行代码上面加上注释，则会被作为这个参数的描述 |\n| 请求 Body | 根据代码生成。比如 gin 里面的 `ctx.Bind(\u0026request)` 参数绑定 |\n| Model 字段描述 | 字段注释 |\n| 接口地址 | 根据代码里面的路由声明自动解析 |\n\n### `@summary`\n\n允许写在 handler 函数的上方。用于设置接口的 `summary`（或者叫标题）。\n\n示例\n```go\n// @summary 创建 XXX 资源\nfunc Create(c *gin.Context) {\n  // your code\n}\n```\n\n### `@required`\n\n用于设置字段是否必填。允许写在 struct 字段注释里 或者 获取请求参数注释里。\n\n\u003e 注意：最新的 OpenAPI 标准中，没有对 **可选字段** 提供支持，只能设置必选字段。\n\n#### 示例1\n\nstruct字段注释\n```go\ntype XxRequest struct {\n  // 我是字段描述\n  // @required\n  Title string `json:\"title\"`\n}\n```\n\n在这个示例里面，\"我是字段描述” 会被显示为文档中的字段描述，并且会被显示为必填字段。\n\n#### 示例2\n\n请求参数获取\n```go\n// Create 创建 XXX 资源接口\nfunc Create(c *gin.Context) {\n  // 分类 ID\n  // @required\n  categoryId := c.Param(\"categoryId\")\n  // @required\n  arg0 := c.Query(\"arg0\")\n  arg1 := c.Query(\"arg1\")\n}\n```\n\n在这个示例里面有三个参数：\n- categoryId Path参数 字段描述:\"分类 ID\" 字段必选\n- arg0 Query参数 无字段描述 必选\n- arg0 Query参数 无字段描述 非必选\n\n### `@consume`\n\n用于设置接口请求 body 的 content-type 。默认为 `application/json`。允许写在 handler 函数注释里面。\n\n示例\n```go\n// @consume application/xml\nfunc Create(c *gin.Context) {\n  var request view.CreateXxRequest\n  err = c.Bind(\u0026request)\n  // ...\n}\n```\n\n在上面这个示例里面，请求参数 request 会被认为是 XML 格式。\n\n### `@produce`\n\n用于设置接口响应 body 的 content-type 。默认为 `application/json`。允许写在 handler 函数注释里面。\n\n示例\n```go\n// @produce application/xml\nfunc Create(c *gin.Context) {\n  var res view.CreateXxResponse\n  // ...\n  c.JSON(http.StatusOK, res)\n}\n```\n\n在上面这个示例里面，响应 Body 数据 res 会被认为是 XML 格式。\n\n### `@ignore`\n\n用于忽略不需要展示在文档中的接口。允许写在以下位置：\n\n1. 代码文件头部：会忽略整个文件的接口\n2. 代码块上方：忽略代码块内的接口\n\n```go\nfunc registerRoutes(g *gin.RouteGroup) {\n  // @ignore\n  {\n    // 代码块内的路由都会被忽略\n    g.GET(\"/v1/resources\", handler.ResourceList)\n    g.POST(\"/v1/resources\", handler.ResourceCreate)\n  }\n\n  // 代码块外面的不会被忽略\n  g.GET(\"/v1/pods\", handler.PodList)\n}\n```\n\n上面这个示例中，代码块内的两个接口都会被忽略，不会展示在文档中。而代码块外面的 `GET /api/pods` 接口则不会被忽略。\n\n3. 函数注释：忽略函数内的接口\n\n```go\n// @ignore\nfunc registerRoutes() {\n  g.GET(\"/v1/resources\", handler.ResourceList)\n  g.POST(\"/v1/resources\", handler.ResourceCreate)\n  g.GET(\"/v1/pods\", handler.PodList)\n}\n```\n\n上面这个示例中，`registerRoutes` 函数内的接口都会被忽略，不会展示在文档中。\n\n### `@tags`\n\n用于设置接口的 Tag 。允许写在 handler 函数的注释、路由定义处的代码块注释、路由定义所在函数注释。设置了相同的 Tag 会在文档内展示在同一个分类下面。\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"docs/operation-tag.jpg\" width=\"120\" /\u003e\u003c/p\u003e\n\n示例\n```go\npackage router\n\n// @tags User\nfunc Create(c *gin.Context) {\n\t// ...\n}\n\nfunc registerRoute2(r *gin.RouterGroup) {\n   // @tags Shop \n   {\n      r.GET(\"/goods\", GoodsList)\n   }\n}\n\n// @tags Hello\nfunc registerRoute(r *gin.RouterGroup) {\n\tr.GET(\"/hello\", Hello)\n}\n```\n\n如上代码所示，三种注释均有效。\n\n如果同时使用了上面三种中的多种注解，优先级为 第一种 \u003e 第二种 \u003e 第三种。\n\n### `@id`\n\n用于设置接口的 `operationId` 。 允许写在 handler 函数注释内。默认值为 handler 所在包名 + 函数名\n\noperationId 除了会被应用在文档内，还会被作为生成的前端代码的函数名。\n\n```go\npackage user\n\n// @id CreateUser\nfunc Create(c *gin.Context) {\n   // ...\n}\n```\n\n在上面这个示例中，`Create` 接口的 operationId 默认为 `user.Create`，但由于设置了 `@id` 注解，所以 operationId 为 \"CreateUser\" 。\n\n### `@deprecated`\n\n用于标记字段或者接口为弃用。允许用于字段注释和 handler 函数注释内。\n\n示例\n```go\ntype User struct {\n  // Use NewField instead\n  // @deprecated\n  OldField string `json:\"xx\"`\n}\n\n// @deprecated\nfunc Create(c *gin.Context) {\n  // ...\n}\n```\n\n### `@security`\n\n用于设置接口鉴权 (Security Requirement) ，参考 https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-requirement-object\n\n```go\n// @security oauth2 pets:write pets:read\nfunc XxxHandler() {\n\t// ...\n}\n```\n\n对应的 securitySchemes 配置示例:\n```yaml\nopenapi:\n  info:\n    title: This is an Example\n    description: Example description for Example\n  securitySchemes:\n    oauth2:\n      type: oauth2\n      flows:\n        implicit:\n          authorizationUrl: \"https://example.org/api/oauth/dialog\"\n          scopes:\n            \"pets:write\": \"modify pets in your account\"\n            \"pets:read\": \"read your pets\"\n```\n\n通常需要配合 securitySchemes 使用，参考 https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object\n\n在上面示例中，`User.OldField` 字段会被标记为弃用，`Create` 函数对应的接口会被标记为弃用。\n\n## 预览\n1. Clickvisual 项目\n  * 文档站: [https://clickvisual.gocn.vip/api](https://clickvisual.gocn.vip/api)\n  * 文档描述文件: [https://github.com/clickvisual/clickvisual/blob/master/api/docs/swagger.json](https://github.com/clickvisual/clickvisual/blob/master/api/docs/swagger.json)\n\n2. gin 示例\n  * [配置文件](https://github.com/link-duan/eapi/blob/main/plugins/gin/testdata/server/eapi.yaml)\n  * [生成文档](https://github.com/link-duan/eapi/blob/main/plugins/gin/testdata/server/docs/openapi.json)\n\n3. echo 示例\n  * [配置文件](https://github.com/link-duan/eapi/blob/main/plugins/echo/testdata/sample/eapi.yaml)\n  * [生成文档](https://github.com/link-duan/eapi/blob/main/plugins/echo/testdata/sample/docs/openapi.json)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgotomicro%2Feapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgotomicro%2Feapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgotomicro%2Feapi/lists"}