全部技能 分类浏览
← 返回
未分类

自动根据代码生成接口文档。支持apifox，postman等等工具

Use when creating new API endpoints (Controller/Service), after implementation compiles successfully. Auto-generates OpenAPI 3.1 documentation. One file per API endpoint.
Use when creating new API endpoints (Controller/Service), after implementation compiles successfully. Auto-generates OpenAPI 3.1 documentation. One file per API endpoint.
宏哥玩AI
未分类 community v1.0.0 3 版本 98823.5 Key: 无需
★ 1
Stars
📥 64
下载
💾 0
安装
3
版本
#latest

概述

OpenAPI 3.1 文档自动生成（单接口模式）

Overview

新接口开发完成后，自动生成符合 OpenAPI 3.1 标准的文档（YAML 格式），每个接口单独生成一份文件，确保 API 文档与代码同步。

When to Use

新接口开发完成
       │
       ├── Model 层 ✓
       ├── Service 层 ✓
       ├── Controller 层 ✓
       ├── 路由注册 ✓
       └── 编译通过 ✓
              │
              ▼
      立即生成 OpenAPI 文档

使用时机：

  • ✅ 新增 POST/GET/PUT/DELETE 接口后
  • ✅ 接口参数变更后
  • ✅ 响应结构修改后

不需要：

  • ❌ 仅修改内部逻辑（接口签名不变）
  • ❌ 数据库 Model 变更（不影响 API）

Quick Reference

项目说明
------------
文档格式OpenAPI 3.1 (YAML)
存放目录docs/openapi/
文件命名{operationId}.yaml
必需字段summary, description, requestBody, responses (200/400/401/500)
Security根据实际代码检测，生成对应的 securitySchemes
可空字段使用 type: ['string', 'null'] 而非 nullable: true

文档结构

每个接口生成独立的 OpenAPI 文档，文件命名规则：

  • docs/openapi/{operationId}.yaml

例如：

  • docs/openapi/wechatLogin.yaml - 微信登录接口
  • docs/openapi/getUserProfile.yaml - 获取用户信息接口
  • docs/openapi/bindPhone.yaml - 绑定手机号接口

文档格式规范

结构顺序

openapi: '3.1.0'
info:
  version: '1.0.0'
  title: '接口标题'
  description: 接口描述
security:              # 鉴权方案，放在根级别
  - TokenAuth: []
paths:
  /api/v1/...:
    parameters:         # 路径参数放在 path 级别，用 $ref 引用 components/schemas
    get:
      summary: ...
      responses:
components:
  schemas:              # 所有数据模型
  securitySchemes:      # 鉴权方案定义

关键规则

  1. 无 servers 段 - 不在文档中硬编码服务器地址
  2. 无 tags 段 - 不在文档中使用标签分组
  3. Security 根据实际代码确定 - 检查接口代码中的鉴权实现，根据实际方式生成对应的 securitySchemes
  4. 路径参数提升到 path 级别 - 路径参数（in: path）放在 path 对象下，通过 $ref 引用 components/schemas 中的类型定义
  5. 无 examples 块 - 不在 schema 中添加 examples
  6. 无 allOf 合并 - 响应直接用 $ref 引用 schema，不使用 allOf 合并 StandardResponse
  7. 可空类型 - OpenAPI 3.1 中使用 type: ['string', 'null'] 代替已废弃的 nullable: true
  8. 字符串值加引号 - openapi: '3.1.0'、version: '1.0.0' 等版本号字符串必须加引号

鉴权方式检测

生成文档时，必须检查接口代码中的实际鉴权实现，根据代码确定 securitySchemes：

常见鉴权模式识别

鉴权方式代码特征OpenAPI securitySchemes
---------------------------------------------
Header Tokenc.Header("token")、c.GetHeader("token")、x-tokentype: apiKey, in: header, name: token
Bearer JWTAuthorization: Bearer、jwt.Parse、Bearer type: http, scheme: bearer
API Key Queryc.Query("api_key")、?api_key=type: apiKey, in: query, name: api_key
Cookiec.Cookie("session")、http.Cookietype: apiKey, in: cookie, name: session
OAuth2oauth2、Bearer token + refreshtype: oauth2, flows: {...}
Basic AuthAuthorization: Basic、base64 编码type: http, scheme: basic
无鉴权公开接口、无中间件、security: []不需要 securitySchemes

检测步骤

  1. 检查中间件 - 查看路由是否挂载了鉴权中间件（如 AuthMiddleware、JWTMiddleware）
  2. 检查 Handler 代码 - 查看是否从 c.Header()、c.Cookie() 等获取凭证
  3. 检查项目鉴权配置 - 查看项目中是否有统一的鉴权配置文件
  4. 确定鉴权方案名称 - 根据检测到的鉴权方式，使用合适的名称（如 TokenAuth、BearerAuth、ApiKeyAuth）

常见框架鉴权代码特征

Go (Gin/Echo):

// Header Token
token := c.GetHeader("token")
token := c.Header("token")

// Bearer JWT
auth := c.GetHeader("Authorization")
if strings.HasPrefix(auth, "Bearer ") { ... }

// Query API Key
apiKey := c.Query("api_key")

// Cookie
token, err := c.Cookie("session_token")

Java (Spring):

// Header Token
@RequestHeader("token") String token
request.getHeader("token");

// Bearer JWT
@RequestHeader("Authorization") String auth
BearerTokenAuthentication

// SecurityContext
SecurityContextHolder.getContext().getAuthentication()

PHP (Laravel):

// Header Token
$request->header('token');
$request->bearerToken(); // Bearer

// Sanctum/Passport
auth('sanctum')->user();

Python (FastAPI/Flask):

# Header Token
token = request.headers.get("token")
token = Header(alias="token")

# Bearer JWT
from fastapi.security import HTTPBearer
HTTPBearer()

单接口文档模板

GET 接口示例（带路径参数）

openapi: '3.1.0'
info:
  version: '1.0.0'
  title: '获取用户个人信息'
  description: 获取当前登录用户的基本信息、绑定状态以及自身的邀请码

security:
  - TokenAuth: []

paths:
  /api/v1/user/{userId}/profile:
    parameters:
      - name: userId
        description: The unique identifier of the user
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UserId'
    get:
      summary: 获取当前用户个人信息
      description: 获取当前登录用户的基本信息、绑定状态以及自身的邀请码。从JWT Token中解析用户ID，返回用户的完整档案信息。
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          description: 未授权，Token无效或过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 服务器错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    UserId:
      description: The unique identifier of a user
      type: integer
      format: int64

    UserProfile:
      description: 用户个人信息
      type: object
      required:
        - id
        - nickname
      properties:
        id:
          $ref: '#/components/schemas/UserId'
        area_code:
          description: 手机国际区号
          type: integer
          format: int32
          minimum: 0
        openid:
          description: 微信OpenID
          type: string
        phone:
          description: 手机号
          type:
            - string
            - 'null'
        nickname:
          description: 昵称
          type: string
        avatar:
          description: 头像URL
          type:
            - string
            - 'null'
        gender:
          description: 性别 1-男 2-女
          type:
            - integer
            - 'null'

    Error:
      description: 错误响应
      type: object
      required:
        - code
        - msg
      properties:
        code:
          description: 错误码
          type: integer
        msg:
          description: 错误信息
          type: string

  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: token
      description: 在请求头中直接传递 token 参数进行鉴权

GET 接口示例（无路径参数）

openapi: '3.1.0'
info:
  version: '1.0.0'
  title: '获取用户个人信息'
  description: 获取当前登录用户的基本信息、绑定状态以及自身的邀请码

security:
  - TokenAuth: []

paths:
  /api/v1/user/profile:
    get:
      summary: 获取当前用户个人信息
      description: 获取当前登录用户的基本信息、绑定状态以及自身的邀请码。从JWT Token中解析用户ID，返回用户的完整档案信息。
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          description: 未授权，Token无效或过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 服务器错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    UserProfile:
      description: 用户个人信息
      type: object
      required:
        - id
        - nickname
      properties:
        id:
          description: 用户ID
          type: integer
          format: int64
        nickname:
          description: 昵称
          type: string

    Error:
      description: 错误响应
      type: object
      required:
        - code
        - msg
      properties:
        code:
          description: 错误码
          type: integer
        msg:
          description: 错误信息
          type: string

  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: token
      description: 在请求头中直接传递 token 参数进行鉴权

POST 接口示例

openapi: '3.1.0'
info:
  version: '1.0.0'
  title: '绑定手机号'
  description: 接收小程序端获取的手机号授权code，由后端向微信服务器换取真实手机号并更新至用户表

security:
  - TokenAuth: []

paths:
  /api/v1/user/bind-phone:
    post:
      summary: 绑定手机号
      description: 接收小程序端获取的手机号授权code，由后端向微信服务器换取真实手机号并更新至用户表。支持更改手机号，且需校验手机号是否已被其他用户绑定。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindPhoneRequest'
      responses:
        '200':
          description: 绑定成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindPhoneResponse'
        '401':
          description: 未授权，Token无效或过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 服务器错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    BindPhoneRequest:
      description: 绑定手机号请求
      type: object
      required:
        - phone_code
      properties:
        phone_code:
          description: 小程序<button open-type="getPhoneNumber">返回的动态code
          type: string

    BindPhoneResponse:
      description: 绑定手机号响应
      type: object
      required:
        - phone
      properties:
        phone:
          description: 绑定的手机号
          type: string

    Error:
      description: 错误响应
      type: object
      required:
        - code
        - msg
      properties:
        code:
          description: 错误码
          type: integer
        msg:
          description: 错误信息
          type: string

  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: token
      description: 在请求头中直接传递 token 参数进行鉴权

无需鉴权接口示例

openapi: '3.1.0'
info:
  version: '1.0.0'
  title: '微信登录'
  description: 通过微信小程序code获取或创建用户，返回JWT Token

paths:
  /api/v1/auth/wechat-login:
    post:
      summary: 微信登录
      description: 通过微信小程序的登录code换取openid，查询或创建用户，返回JWT Token用于后续接口鉴权。
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WechatLoginRequest'
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WechatLoginResponse'
        '400':
          description: 参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 服务器错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    WechatLoginRequest:
      description: 微信登录请求
      type: object
      required:
        - code
      properties:
        code:
          description: 微信小程序wx.login()获取的临时登录凭证
          type: string

    WechatLoginResponse:
      description: 微信登录响应
      type: object
      required:
        - token
      properties:
        token:
          description: JWT Token，用于后续接口鉴权
          type: string

    Error:
      description: 错误响应
      type: object
      required:
        - code
        - msg
      properties:
        code:
          description: 错误码
          type: integer
        msg:
          description: 错误信息
          type: string

字段类型映射

Go 类型映射

Go 类型OpenAPI 3.1 类型
----------------------------
stringtype: string
int, int64type: integer, format: int64
int32type: integer, format: int32
uint32type: integer, format: int32, minimum: 0
float64type: number
float32type: number, format: float
booltype: boolean
time.Timetype: string, format: date-time
*Ttype: [T, 'null'] （数组类型表示可空）
[]Ttype: array, items: { type: T }
map[string]Ttype: object, additionalProperties: { type: T }
interface{}type: object

Java 类型映射

Java 类型OpenAPI 3.1 类型
------------------------------
Stringtype: string
int, Integertype: integer, format: int32
long, Longtype: integer, format: int64
short, Shorttype: integer, format: int32
double, Doubletype: number, format: double
float, Floattype: number, format: float
BigDecimaltype: number
boolean, Booleantype: boolean
LocalDatetype: string, format: date
LocalTimetype: string, format: time
LocalDateTimetype: string, format: date-time
Datetype: string, format: date-time
OffsetDateTimetype: string, format: date-time
ZonedDateTimetype: string, format: date-time
UUIDtype: string, format: uuid
List\type: array, items: { type: T }
Set\type: array, items: { type: T }, uniqueItems: true
Map\type: object, additionalProperties: { type: T }
Objecttype: object
Optional\type: [T, 'null']
@Nullable Ttype: [T, 'null']
Enumtype: string, enum: [value1, value2, ...]

PHP 类型映射

PHP 类型OpenAPI 3.1 类型
-----------------------------
stringtype: string
inttype: integer, format: int64
floattype: number, format: double
booltype: boolean
arraytype: array, items: { type: T }
objecttype: object
nulltype: 'null'
mixed不映射，需根据上下文确定
DateTimetype: string, format: date-time
DateTimeInterfacetype: string, format: date-time
Carbontype: string, format: date-time
?T（可空类型）type: [T, 'null']
Collectiontype: array, items: { type: T }
enumtype: string, enum: [value1, value2, ...]（PHP 8.1+）
backed enum (int)type: integer, enum: [1, 2, ...]

Python 类型映射

Python 类型OpenAPI 3.1 类型
--------------------------------
strtype: string
inttype: integer, format: int64
floattype: number, format: double
booltype: boolean
bytestype: string, format: byte
decimal.Decimaltype: number
datetime.datetype: string, format: date
datetime.timetype: string, format: time
datetime.datetimetype: string, format: date-time
uuid.UUIDtype: string, format: uuid
list\[T\]type: array, items: { type: T }
tuple\[T, ...\]type: array, items: { type: T }
set\[T\]type: array, items: { type: T }, uniqueItems: true
dict\[str, T\]type: object, additionalProperties: { type: T }
Optional\[T\]type: [T, 'null']
T \Nonetype: [T, 'null']
Union\[T1, T2\]oneOf: [{ type: T1 }, { type: T2 }]
Literal\["a", "b"\]type: string, enum: ["a", "b"]
Enumtype: string 或 type: integer, enum: [...]

可空类型说明（OpenAPI 3.1）

OpenAPI 3.1 移除了 nullable: true，改用类型数组：

# 旧写法（3.0）
phone:
  type: string
  nullable: true

# 新写法（3.1）
phone:
  type:
    - string
    - 'null'

Implementation Steps

  1. 分析接口签名
    • 读取 Controller 中的路由定义
    • 确认请求方法（GET/POST/PUT/DELETE）
    • 确认请求参数（Query/Path/Body）
    • 确认是否需要鉴权
  1. 检测实际鉴权实现（必须执行代码扫描）

> 这一步不是描述，而是必须执行的动作。 使用 Grep/Glob/Read 工具扫描项目代码。

Step 2a - 扫描中间件文件：

  • 用 Glob 搜索 /middleware/、/auth、/jwt 等文件
  • 用 Grep 搜索关键词：Auth、Token、JWT、Authorization、Bearer
  • 读取匹配的中间件文件，确认鉴权逻辑

Step 2b - 扫描路由注册：

  • 用 Glob 搜索 /router、/route、*/routes 文件
  • 读取路由文件，查看哪些路由组挂载了鉴权中间件
  • 确认当前接口是否在鉴权路由组内

Step 2c - 扫描 Controller/Handler：

  • 读取当前接口的 Controller/Handler 代码
  • 检查是否从 Header/Cookie/Query 获取凭证
  • 确认凭证的 key 名称（如 token、Authorization、api_key）

Step 2d - 根据扫描结果确定 securitySchemes：

| 扫描到的代码特征 | 生成的 securitySchemes |

|------------------|------------------------|

| c.GetHeader("token") / c.Header("token") / x-token | TokenAuth: { type: apiKey, in: header, name: token } |

| c.GetHeader("Authorization") + Bearer | BearerAuth: { type: http, scheme: bearer } |

| c.Query("api_key") / ?api_key= | ApiKeyAuth: { type: apiKey, in: query, name: api_key } |

| c.Cookie("session") / http.Cookie | CookieAuth: { type: apiKey, in: cookie, name: session } |

| Authorization: Basic / base64 | BasicAuth: { type: http, scheme: basic } |

| 路由未挂载鉴权中间件 | security: []（不生成 securitySchemes） |

判断是否需要鉴权：

  • 路由在鉴权中间件组内 → 根级别 security: [{方案名}: []]
  • 路由不在鉴权中间件组内 → operation 级别 security: []
  • 不确定 → 提示用户确认
  1. 提取请求/响应模型
    • 读取 requestModel 中的请求体结构
    • 读取 responseModel 中的响应体结构
  1. 生成单接口文档
    • 创建 docs/openapi/{operationId}.yaml
    • 按照格式规范填充：openapi, info, security, paths, components
    • 根据步骤 2 检测结果 生成正确的 security 和 securitySchemes
    • 路径参数放在 path 级别并用 $ref 引用 components/schemas
    • 请求体和响应体也用 $ref 引用 components/schemas
    • 可空字段使用 type: [T, 'null'] 格式
  1. 验证文档
    • 确保 YAML 格式正确
    • 确保 schema 引用完整（所有 $ref 指向的 schema 都在 components/schemas 中定义）
    • 确保 securitySchemes 与实际代码鉴权方式一致
    • 导入 Apifox 或其他工具测试

目录结构

docs/
└── openapi/
    ├── wechatLogin.yaml
    ├── getUserProfile.yaml
    ├── bindPhone.yaml
    └── updateUserProfile.yaml

Common Mistakes

错误正确做法
----------------
使用 openapi: 3.0.3必须使用 openapi: '3.1.0'
使用 nullable: true使用 type: [T, 'null'] 数组格式
使用 servers 段OpenAPI 3.1 文档不包含 servers
使用 tags 段OpenAPI 3.1 文档不包含 tags
直接套用固定鉴权模板必须检查代码中实际的鉴权实现，生成对应的 securitySchemes
securitySchemes 与代码不符检测代码中的 Header/Cookie/Query/Bearer 等实际鉴权方式
Security 放在 operation 级别需要鉴权的接口使用根级别 security
路径参数放在 operation 内路径参数必须放在 path 级别
使用 allOf 合并响应直接用 $ref 引用完整 schema
添加 examples 块不添加 examples，保持简洁
指针类型没有标记可空Go 的 *T 类型必须用 type: [T, 'null']
单接口文档缺少 components每个文档都必须包含完整的 components
$ref 引用的 schema 未定义所有引用的 schema 必须在 components/schemas 中定义

Red Flags

  • 写完接口就直接提交，没有更新文档
  • 没有检查实际代码的鉴权实现，直接套用固定的 securitySchemes
  • securitySchemes 与代码实际鉴权方式不符（如代码用 Header Token 却写成 Bearer JWT）
  • 需要鉴权的接口没有在根级别配置 security
  • 不需要鉴权的接口没有在 operation 中用 security: [] 覆盖
  • 响应 schema 与实际代码中的响应结构不一致
  • 单接口文档中引用了不存在的 schema

版本历史

共 1 个版本

  • v1.0.0 Initial release 当前
    2026-05-26 15:51 安全 安全

安全检测

腾讯云安全 (Keen)

安全，无风险
查看报告

腾讯云安全 (Sanbu)

安全，无风险
查看报告

🔗 相关推荐

developer-tools

Github

steipete
使用 `gh` CLI 与 GitHub 交互，通过 `gh issue`、`gh pr`、`gh run` 和 `gh api` 管理议题、PR、CI 运行及高级查询。
★ 668 📥 324,165
ai-intelligence

Self-Improving + Proactive Agent

ivangdavila
自我反思+自我批评+自我学习+自组织记忆。智能体评估自身工作、发现错误并持续改进。
★ 1,358 📥 318,376
security-compliance

Skill Vetter

spclaudehome
AI智能体技能安全预审工具。安装ClawdHub、GitHub等来源技能前，检查风险信号、权限范围及可疑模式。
★ 1,215 📥 266,540

Skill工具集 © 2026