common-api-doc
基于OpenAPI规范生成API文档，支持Swagger UI和ReDoc展示
Informações da origem
- Repositório
- bage2014/study
- Última atividade na origem
- 24 de junho de 2026 às 23:18
- Idioma detectado do SKILL.md
- chinês
- Estrelas
- 646
- Forks
- 113
Opções de instalação
Por padrão, está selecionado o prompt que primeiro revisa a origem. Você pode mudar para um comando direto ou baixar uma cópia local.
Revise os arquivos de origem
Leia o SKILL.md e os arquivos complementares exibidos pelo SkillsMP antes de decidir se vai instalar.
Exibindo SKILL.md
SKILL.md
Instruções da origem · Visualização somente leitura- name
- common-api-doc
- description
- 基于OpenAPI规范生成API文档，支持Swagger UI和ReDoc展示
- trigger
- 用户需要生成或更新API文档时
- disable-when
- 项目未使用RESTful API或已有完善文档
- category
- backend
- tags
- ["api","swagger","openapi","documentation"]
# API文档生成技能
## 功能描述
根据代码或需求自动生成 OpenAPI/Swagger 文档，支持交互式文档界面。
## 何时使用
- 后端 API 开发完成后生成文档
- 根据接口需求生成 API 规范
- 维护 API 文档
## 核心功能
- 从代码注释生成 OpenAPI 规范
- 从需求描述生成 API 设计
- 生成 Swagger UI 界面
- 导出多种格式（YAML/JSON/HTML）
## 输入参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sourceType | String | 是 | 来源类型（code/requirements） |
| source | String | 是 | 代码路径或需求描述 |
| outputFormat | String | 否 | 输出格式（yaml/json/html，默认 yaml） |
| serverUrl | String | 否 | API 服务地址 |
## 输出格式
```json
{
"status": "SUCCESS",
"openapiVersion": "3.0.3",
"outputFile": "openapi.yaml",
"endpoints": [
{"method": "GET", "path": "/api/users", "summary": "获取用户列表"},
{"method": "POST", "path": "/api/users", "summary": "创建用户"},
{"method": "GET", "path": "/api/users/{id}", "summary": "获取用户详情"}
],
"swaggerUiUrl": "http://localhost:8080/swagger-ui.html"
}
```
## 使用流程
1. 指定来源类型（代码或需求）
2. 提供代码路径或需求描述
3. 选择输出格式
4. 生成 API 文档
## 最佳实践
- 在 CI/CD 流程中自动更新文档
- 使用 SpringDoc 集成 Swagger UI
- 保持 API 文档与代码同步
## 配置要求
### Spring Boot 集成示例
```yaml
springdoc:
api-docs:
path: /api-docs
swagger-ui:
path: /swagger-ui.html
```
## 扩展指南
支持自定义模板和文档样式。
## 触发条件
Ver no GitHub