如何快速为现有Web服务生成完整的OpenAPI规范？

算力阿峰

2026-7-31

获取运行中RESTful API的OpenAPI规范的有效方法

检查服务器自带的规范端点
多数主流Web框架（如Spring Boot、FastAPI）会自动生成并暴露OpenAPI规范，常见的访问路径包括/openapi.json、/swagger.json或/api-docs，直接发送GET请求就能获取完整的规范文件。
通过API流量录制生成
如果服务器没有内置规范输出，可以通过录制实际API调用流量来生成：
- 用curl批量调用所有已知API接口，导出请求和响应数据后，借助openapi-generator工具转换为OpenAPI规范；
- 使用Postman、Insomnia等API客户端，完成所有API调用后直接导出为OpenAPI格式；
- 利用mitmproxy这类代理工具拦截所有API请求，自动生成包含全部接口的规范。
基于代码注释自动生成
若能获取后端代码，可通过框架自带的注释生成能力导出规范：
- Java/Spring Boot：使用Springdoc OpenAPI，通过@Operation、@ApiResponse等注解自动生成；
- Python/FastAPI：框架本身依托Pydantic和类型提示，默认生成OpenAPI规范；
- Node.js/Express：借助swagger-jsdoc库，通过JSDoc注释提取接口信息生成规范。
手动补全与验证
若工具生成的规范存在遗漏，可先导出基础版本，再对照API文档或实际调用补充缺失的接口、参数、响应模型，最后用openapi-cli工具验证规范的语法正确性和完整性。