Common API Doc

Documents

common-api-doc

Common API Doc is an Agent Skill for documents published in the bage2014/study repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

基于OpenAPI规范生成API文档，支持Swagger UI和ReDoc展示

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/bage2014/study/blob/HEAD/study-ai-skills/skills/common-api-doc/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/common-api-doc, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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 服务地址

输出格式

{
  "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"
}

使用流程

指定来源类型（代码或需求）
提供代码路径或需求描述
选择输出格式
生成 API 文档

最佳实践

在 CI/CD 流程中自动更新文档
使用 SpringDoc 集成 Swagger UI
保持 API 文档与代码同步

配置要求

Spring Boot 集成示例

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html

扩展指南

支持自定义模板和文档样式。