⚡

OpenAPI规范生成器 openapi-spec-generator

OpenAPI规范生成器是一个自动化工具，用于从源代码的注释、注解和接口定义中提取信息，自动生成符合OpenAPI 3.x标准的API规范文档。它支持多种主流开发框架，能有效提升API文档编写的效率和准确性，是API设计、文档管理和SDK生成流程中的关键工具。关键词：OpenAPI规范生成，API文档自动化，代码解析，RESTful API，接口文档，开发工具。

后端开发 0 次安装 0 次浏览 更新于 2/26/2026

名称: openapi-spec-generator 描述: 从代码注释、注解和接口定义中自动生成OpenAPI规范 允许使用的工具:

  • 读取
  • 写入
  • 编辑
  • 全局搜索
  • 文本搜索
  • Bash

OpenAPI规范生成器技能

概述

本技能通过解析源代码，自动从代码注释、注解和接口定义中提取API端点、数据模型和文档，生成全面且准确的OpenAPI 3.x规范。

能力

  • 解析代码，从注解中提取API端点和数据模型
  • 生成YAML或JSON格式的OpenAPI 3.x规范
  • 根据OpenAPI标准验证规范的完整性和正确性
  • 通过增量生成，根据代码变更自动更新规范
  • 支持多种框架（Express, FastAPI, Spring, ASP.NET等）
  • 从TypeScript类型、Python类型提示、Go结构体等提取请求/响应数据模型
  • 根据代码级文档生成示例

目标流程

  • API设计规范制定
  • API文档系统
  • SDK代码生成流水线

集成点

  • 代码分析工具（抽象语法树解析器）
  • 模式验证器（Spectral, openapi-spec-validator）
  • Swagger/OpenAPI工具生态系统
  • 用于规范预览的IDE扩展

输入要求

  • 包含API路由定义的源代码
  • 代码库中使用的注解/装饰器约定
  • 目标OpenAPI版本（3.0.x 或 3.1.x）
  • 输出格式偏好（YAML/JSON）

输出产物

  • OpenAPI规范文件（openapi.yaml 或 openapi.json）
  • 包含发现问题的验证报告
  • 数据模型提取摘要
  • 与先前规范版本的变更差异（如适用）

使用示例

技能:
  名称: openapi-spec-generator
  上下文:
    源代码目录: ./src/api
    框架: express
    输出格式: yaml
    openapi版本: "3.1.0"
    包含示例: true

最佳实践

  1. 在整个代码库中使用一致的注解模式
  2. 为所有端点包含JSDoc/文档字符串
  3. 定义可复用的数据模型组件
  4. 在发布前验证生成的规范
  5. 对生成的规范进行版本控制