# Swagger API 生成说明

## 方案选择

根据项目架构（BFF层Gin + 微服务gRPC），推荐使用 **grpc-gateway** 方案：

1. ✅ 自动从proto生成REST API代码
2. ✅ 自动生成Swagger/OpenAPI文档
3. ✅ 保持proto和REST API的一致性
4. ✅ 支持同时提供gRPC和REST两种接口

## 方案对比

| 方案 | 优点 | 缺点 | 适用场景 |
|------|------|------|---------|
| **grpc-gateway** | 自动生成、一致性高 | 需要在proto中添加注解 | ✅ **推荐**：需要同时支持gRPC和REST |
| 手动编写Swagger | 灵活性高 | 工作量大、易不一致 | 接口差异大时 |
| protoc-gen-openapiv2 | 直接生成OpenAPI | 不能生成REST API代码 | 只需要文档时 |

## 安装依赖

### 1. 安装 Protocol Buffers 编译器

```bash
# macOS
brew install protobuf

# 或下载预编译版本
# https://github.com/protocolbuffers/protobuf/releases
```

### 2. 安装 Go 插件

```bash
# grpc-gateway 相关插件
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest

# 标准 proto 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
```

### 3. 安装 Swagger UI（可选，用于查看文档）

```bash
# 方式1：使用 Docker
docker run -p 8080:8080 -e SWAGGER_JSON=/foo/swagger.json -v $(pwd)/swagger:/foo swaggerapi/swagger-ui

# 方式2：使用 npm
npm install -g swagger-ui-serve
```

## 使用步骤

### 步骤1：在proto文件中添加REST API注解

需要在proto文件中添加 `google/api/annotations.proto` 的注解：

```protobuf
import "google/api/annotations.proto";

service UserSocialService {
  rpc Login(LoginRequest) returns (LoginResponse) {
    option (google.api.http) = {
      post: "/api/v1/auth/login"
      body: "*"
    };
  }
  
  rpc GetUser(GetUserRequest) returns (GetUserResponse) {
    option (google.api.http) = {
      get: "/api/v1/users/{user_id}"
    };
  }
}
```

### 步骤2：生成代码和Swagger

运行 Makefile 中的命令：

```bash
make swagger  # 生成REST API代码和Swagger文档
```

### 步骤3：在Gin中使用生成的代码

生成的代码可以直接在Gin中注册路由。

## 目录结构

```
top-fans/
├── proto/              # Proto定义文件
├── swagger/            # Swagger相关文件
│   ├── swagger.json    # 生成的Swagger JSON（自动生成）
│   ├── swagger.yaml    # 生成的Swagger YAML（自动生成）
│   └── README.md       # 本文档
├── api/                # 生成的REST API代码（自动生成）
│   └── gateway/        # grpc-gateway生成的代码
└── Makefile            # 包含生成命令
```

## 注意事项

1. **Proto和REST API的关系**
   - Proto定义是"源"，REST API是"派生"
   - 修改接口时，先改proto，再重新生成

2. **路径设计**
   - REST API路径应遵循RESTful规范
   - 与proto的RPC方法名可以不同

3. **认证方式**
   - REST API使用Bearer Token（JWT）
   - 在Swagger中配置Security Scheme

4. **错误处理**
   - gRPC错误码需要映射到HTTP状态码
   - 使用grpc-gateway的默认映射或自定义