apipost

README

ApiPost 接口文档自动化生成工具

基于 Go AST 静态分析，零配置自动生成 ApiPost 接口文档

🌟 项目简介

ApiPost 是一个强大的接口文档自动化生成工具，通过静态分析 Go 代码，自动提取 Controller 路由信息、请求/响应结构体，并生成完整的 ApiPost 接口文档。无需手动编写文档，大幅提升开发效率。

✨ 核心特性

🚀 零配置，开箱即用

• 自动识别项目结构（支持任意包名和目录布局）
• 智能定位模型包和 Service 层
• 无需手动指定 -iapi 参数

🧠 智能解析

• 路由解析：自动提取 HTTP 方法、路径、注释
• 类型推断：支持本地 Service 和外部 SDK 调用
• 深度解析：递归解析任意层级的嵌套结构体

📦 广泛兼容

• 本地包：iapi、entity、model、dto 或任意自定义包名
• 外部 SDK：自动解析 go.mod 依赖（如 scrm、openapi 等）
• 目录结构：./models/、./app/、./internal/ 等任意布局

🎯 精准生成

• GET/DELETE 请求参数自动放入 query
• POST/PUT/PATCH 请求参数自动放入 body
• 完整的 JSON Schema（类型、注释、必填标记、字段顺序）
• 自动生成请求/响应示例

📦 安装

go install gitee.com/go_common/apipost@latest

⚙️ 配置

配置 ApiPost Token

在 ~/.zshrc 或 ~/.bashrc 中添加：

export APIPOST_TOKEN=your_token_here

执行 source ~/.zshrc 使其生效。

获取 Token 和项目 ID

1. 获取 Token：登录 ApiPost → 用户设置 → API Token
2. 获取项目 ID：打开项目 → 项目设置 → 项目 ID

🚀 快速开始

基本用法

# 创建接口
apipost -project <项目ID> -ctl <Controller文件路径> -method <方法名>

# 预览模式（不实际创建）
apipost -project <项目ID> -ctl <Controller文件路径> -method <方法名> -dry-run

使用示例

# 示例 1：创建用户详情接口
apipost \
  -project 1b4da74a8bf15001 \
  -ctl ./app/controller/userctl/userctl.go \
  -method UserDetail

# 示例 2：预览接口 JSON
apipost \
  -project 1b4da74a8bf15001 \
  -ctl /path/to/controller.go \
  -method MethodName \
  -dry-run

# 示例 3：从任意目录执行
cd /tmp
apipost -project xxx -ctl /Users/xxx/project/app/controller/xxx.go -method xxx

📋 参数说明

参数	必填	默认值	说明
-project	✅	-	ApiPost 项目 ID（在 ApiPost 项目设置中获取）
-ctl	✅	-	Controller 文件的绝对或相对路径
-method	✅	-	Controller 中的方法名（如 UserDetail）
-token	❌	$APIPOST_TOKEN	ApiPost API Token（优先使用环境变量）
-iapi	❌	自动识别	模型目录路径（通常无需指定，工具自动识别）
-dry-run	❌	false	预览模式：仅输出 JSON，不调用 API

🔧 工作原理

Controller 文件
    ↓
解析路由定义 → 提取 HTTP 方法、路径、注释
    ↓
解析方法签名 → 识别请求/响应类型
    ↓
定位结构体 → 本地包 or 外部 SDK
    ↓
递归解析 → 生成完整 JSON Schema
    ↓
生成 ApiPost JSON → 调用 API 创建接口

📝 输出示例

📍 解析到路由: POST /admin/user/detail
📝 接口名称: 用户详情接口
📥 请求类型: entity.UserDetailReq
📤 响应类型: entity.UserDetailResp

🚀 正在创建新接口...
✅ 接口创建成功!
   - Target ID: 36d3b5c79acfb
   - 名称: 用户详情接口
   - 版本: 1

🏗️ 支持的项目结构

✅ 本地包

import (
    "project/models/entity"     // ✅ entity 包
    "project/models/iapi"        // ✅ iapi 包
    "project/app/dto"            // ✅ dto 包
    "project/internal/model"     // ✅ 任意包名
)

✅ 外部 SDK

import (
    "git.100tal.com/xxx/openapi_sdk/openapi/scrm"  // ✅ 外部 SDK
    "github.com/xxx/api-client"                     // ✅ GitHub 包
)

✅ Service 目录

project/
├── services/xxxservice/          ✅ 标准结构
├── models/service/xxxservice/    ✅ 嵌套结构
└── app/service/xxxservice/       ✅ 应用层结构

🎨 高级特性

1. 嵌套结构体解析

支持任意深度的嵌套：

type Request struct {
    List []Item  // ✅ 数组
}

type Item struct {
    SubList []SubItem  // ✅ 嵌套数组
}

type SubItem struct {
    Details []Detail  // ✅ 多层嵌套
}

2. 外部 SDK 类型推断

自动推断外部 API 返回类型：

// Controller 代码
data, err = api.ScrmOpenApi(ctx).UserDetail(ctx, req)

// 自动推断
// 请求类型: scrm.UserDetailReq
// 响应类型: scrm.UserDetailResp  ← 自动从 Req 推断为 Resp

3. 路径无关执行

无论从哪个目录执行，都能正确定位：

# 从项目根目录
cd /path/to/project
apipost -project xxx -ctl ./app/controller/xxx.go -method xxx

# 从任意目录
cd /tmp
apipost -project xxx -ctl /path/to/project/app/controller/xxx.go -method xxx

❓ 故障排除

Token 未找到

错误: 未找到 ApiPost Token

解决方案：
1. 设置环境变量: export APIPOST_TOKEN=your_token
2. 或使用参数: -token your_token
3. 或使用预览模式: -dry-run

响应类型未找到

📤 响应类型: (未找到)

可能原因：
1. Service 方法未返回具体类型（返回 interface{}）
2. 外部 API 调用无法推断类型

解决方案：
- 检查 Service 方法签名
- 确保返回值有明确的类型声明

结构体解析失败

警告: 解析响应结构体 xxx 失败

可能原因：
1. 结构体定义在未导入的包中
2. 包路径无法定位

解决方案：
- 检查 import 语句是否正确
- 确保 go.mod 依赖完整

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发环境

git clone https://gitee.com/go_common/apipost.git
cd apipost
go mod download
go build -o bin/apipost

测试

# 运行测试
go test ./...

# 本地测试
./bin/apipost -dry-run -project xxx -ctl /path/to/controller.go -method xxx

📚 项目结构

apipost/
├── main.go              # 主程序入口
├── client.go            # ApiPost API 客户端
├── generator.go         # JSON 生成器
├── parser/              # 解析器包
│   ├── controller_parser.go  # Controller 解析器
│   ├── struct_parser.go      # 结构体解析器
│   └── schema.go             # Schema 定义
├── go.mod
├── go.sum
└── README.md

📄 License

MIT License

📧 联系方式

• Issues: 提交问题
• QQ: 1713540519

---

⭐ 如果这个项目对你有帮助，请给个 Star！