{"repo":"gotomicro/eapi","free":true,"listed":false,"github":"https://github.com/gotomicro/eapi","clone":"git clone https://github.com/gotomicro/eapi.git","description":"一个通过分析 AST 生成 Swagger 文档的工具","language":"Go","stars":31,"topics":["openapi","docs","gin","swagger"],"license":"MIT","category":"api-integrations-sdks","readme_excerpt":"eAPI 一个通过分析代码生成 OpenAPI 文档的工具 介绍 eAPI 通过分析 AST 生成 接口文档 及 前端代码 。与 swaggo/swag 等工具不同之处在于，eAPI 无需编写注解即可使用。另外，eAPI 还支持生成 Typescript 类型代码 和 前端接口请求代码。 eAPI 首先解析出代码中的路由（方法/路径）声明，得到接口的 Path、Method 及对应的 Handler 函数。然后再对 Handler 函数进行解析，得到 请求参数（Query/FormData/JSON-Payload等）、响应数据等信息。最终生成一份符合 OpenAPI 3 标准的 JSON 文档。 eAPI 目前支持了 gin, echo 框架的文档生成，其他主流框架在计划中。如果你需要将 eAPI 应用在其他未被支持的框架，可以通过编写自定义插件的方式进行实现，或者给我们提交 PR。 安装 如何使用 1. 创建配置文件 在代码根目录创建配置文件 eapi.yaml : 2. 生成文档 在代码根目录执行命令: 执行完成后会在 docs 目录下生成 openapi.json 文件。 完整的配置说明 配置 如下是完整的配置文件示例: Properties properties 用于配置自定义请求参数绑定函数和响应输出函数。 自定义请求参数绑定函数 配置示例： 自定义响应输出函数 配置示例： 其中，data type 可选值为： - string - number - integer - boolean - array - file - object 此外，还可以将函数入参作为参数类型，eAPI 会自动解析对应的参数类型。比如 args[0] 代表函数第一个参数。 完整的配置参考 https://github.com/link-duan/eapi/blob/main/plugins/common/config.go 下面的 DataSchema 类型声明。 代码生成器配置 如果需要使用代码生成功能，需要在配置文件内添加如下配置: umi-request 请求代码生成 umi 代码生成器用于生成适用于使用 umi.js 框架的前端接口请求代码及 TypeScript 类型。 示例配置： Typescript 类型生成 ts 代码生成器用于生成 TypeScript 类型代码。 示例配置： 注解 如果你需要对文档的内容进行更精细化的调整（比如接口标题、字段是否必选等），那么你需要使用到注解。 默认情况 如果没有写注解，eAPI 也会帮你生成关于接口的必要信息。对应关系如下： 接口信息 默认值 :- :- 接口的 summary (标题) pkg.HandlerName handler 函数所在的包名和函数名共同组成接口标题。如果有注释，会默认使用注释作为标题 接口描述 handler 函数的注释（非注解部分） Path/Query/Form参数 根据代码生成。比如 gin 里面的 ctx.Query(\"q\") 会被解析为 query 参数 q 。如果在这行代码上面加上注释，则会被作为这个参数的描述 请求 Body 根据代码生成。比如 gin 里面的 ctx.Bind(&request) 参数绑定 Model 字段描述 字段注释 接口地址 根据代码里面的路由声明自动解析 @summary 允许写在 handler 函数的上方。用于设置接口的 summary （或者叫标题）。 示例 @required 用于设置字段是否必填。允许写在 struct 字段注释里 ","default_branch":null,"files":null,"tree":[],"storefront":"/r/gotomicro","claimed":false,"request_supported":{"post":"https://gitbuyer.com/r/gotomicro/eapi/request-supported","requests":0},"note":"indexed from public GitHub; nothing is for sale on this page. Clone it from GitHub. Paid listings live at /search."}