# OpenAPI 文档自动生成功能

## 功能概述

服务启动时自动生成 OpenAPI 3.0 规范文档，确保文档始终与运行的服务保持同步。

## 使用方式

### 1. 自动生成（服务启动时）

当你启动 API 服务时，OpenAPI 文档会自动生成:

```bash
make run
# 或
go run cmd/api/main.go
```

文档将自动保存到项目根目录: `./openapi.yaml`

### 2. 手动生成（独立工具）

如果需要离线生成文档（不启动服务），可以使用以下命令:

```bash
make docs
# 或
go run cmd/gendocs/main.go
```

文档将保存到: `./docs/admin-openapi.yaml`

## 实现细节

### 核心文件

- `cmd/api/docs.go` - 服务启动时的文档生成逻辑
- `cmd/api/main.go` - 在步骤 11 调用文档生成
- `cmd/gendocs/main.go` - 独立文档生成工具

### 生成流程

1. 创建 OpenAPI 文档生成器
2. 创建临时 Fiber App
3. 注册所有路由（使用 nil 依赖）
4. 保存文档到指定路径
5. 生成失败时记录错误但不影响服务

### 错误处理

- 文档生成失败会记录到应用日志
- 服务启动不会因文档生成失败而中断
- 保证服务的可用性优先于文档生成

## 技术架构

### 避免循环依赖

文档生成逻辑放在各自的 `cmd/` 包内，避免了 `pkg/openapi` → `internal/routes` 的循环依赖。

### 代码复用

两种生成方式（自动和手动）都使用相同的核心逻辑:
- 相同的路由注册机制
- 相同的文档生成器
- 仅输出路径不同

## 配置

### .gitignore

自动生成的文档已添加到 `.gitignore`:
```
/openapi.yaml
```

这避免了将自动生成的文件提交到版本控制。

## 验证

### 编译测试
```bash
go build ./cmd/api
go build ./cmd/gendocs
```

### 功能测试
```bash
# 测试独立工具
make docs

# 检查生成的文档
ls -lh docs/admin-openapi.yaml
```

## 相关文档

- [提案](./proposal.md) - 功能需求和设计思路
- [任务清单](./tasks.md) - 实现任务列表
- [实现总结](./IMPLEMENTATION.md) - 详细的实现说明
- [规范](./specs/openapi-generation/spec.md) - 正式的功能规范