Swagger 是一套围绕 OpenAPI 规范构建的开源工具集用于设计、构建、记录和使用 RESTful API。Swagger 提供了一种标准化的方式来描述 API 的结构使得开发者和机器都能理解 API 的功能而无需访问源代码或其他文档。Swagger 的核心价值在于标准化提供统一的 API 描述格式可视化自动生成交互式 API 文档可测试性允许直接在文档中测试 API 端点代码生成支持多种语言的客户端和服务端代码生成Swagger 核心组件组件输入输出适用阶段Swagger Editor手动编写 YAML/JSON实时预览的 API 文档API 设计阶段Swagger UIOpenAPI 文件交互式网页文档开发/测试阶段Swagger CodegenOpenAPI 文件客户端/服务端代码前后端协作阶段组件协作流程图Swagger Editor设计API ↓ OpenAPI 规范文件YAML/JSON ↓ Swagger UI展示文档 或 Swagger Codegen生成代码Swagger 核心组件详解1. Swagger EditorSwagger Editor 是基于浏览器的可视化编辑器用于编写和实时预览 OpenAPI 规范YAML/JSON 格式。Swagger Editor 提供语法高亮、自动补全和错误校验。Swagger Editor 代码生成、保存和导出功能现已加入 SmartBear API Hub访问地址https://try.platform.smartbear.com/new-organization。使用场景快速设计 API 原型学习 OpenAPI 规范语法访问在线编辑器 Swagger EditorSwaggerEditor输入以下 YAML 代码定义一个简单的 GET /users 接口实例span stylecolor: green;openapi: 3.0.3info:title: RUNOOB 用户管理系统version: 1.0.0paths:/users:get:summary: 获取用户列表responses:200:description: 成功返回用户列表content:application/json:schema:type: arrayitems:type: objectproperties:id:type: integername:type: string右侧将实时渲染出 API 文档和交互式 UI。Swagger UISwagger UI 将 OpenAPI 规范转换为可视化交互式文档支持直接在浏览器中测试 API。Swagger UI 会自动生成请求示例、响应模型和调试界面。Swagger UI: REST API Documentation Tool | Swagger UI使用场景团队共享 API 文档前端开发者调试接口集成示例以 Node.js 为例,安装依赖npm install swagger-ui-express swagger-jsdoc创建 swagger.js 配置文件实例const swaggerJSDoc require(swagger-jsdoc);const options {definition: {openapi: 3.0.0,info: { title: 用户API, version: 1.0.0 },},apis: [./routes/*.js], // 扫描路由文件中的注释};const swaggerSpec swaggerJSDoc(options);module.exports swaggerSpec;在 Express 中挂载 UI实例const express require(express);const swaggerUi require(swagger-ui-express);const swaggerSpec require(./swagger);const app express();app.use(/api-docs, swaggerUi.serve, swaggerUi.setup(swaggerSpec));访问 http://localhost:3000/api-docs 查看文档。Swagger CodegenSwagger Codegen 根据 OpenAPI 规范自动生成客户端 SDK如 Java、Python或服务端桩代码如 Spring、Flask。Swagger Codegen 支持自定义模板。下载页面API Code Client Generator | Swagger Codegen使用场景快速生成 API 调用的客户端代码服务端接口自动化开发操作示例命令行生成 Java 客户端, 下载 Swagger Codegen CLIwget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar生成代码java -jar swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l java \ -o ./petstore-api-clientSwagger Hub可选扩展Swagger Hub 是 Swagger 的云端平台提供协作设计、版本管理和托管文档。Swagger Hub 支持团队协作和 API 生命周期管理。使用场景企业级 API 项目管理需要在线协作的分布式团队 HoRain云--Swagger 核心组件
Swagger 是一套围绕 OpenAPI 规范构建的开源工具集用于设计、构建、记录和使用 RESTful API。Swagger 提供了一种标准化的方式来描述 API 的结构使得开发者和机器都能理解 API 的功能而无需访问源代码或其他文档。Swagger 的核心价值在于标准化提供统一的 API 描述格式可视化自动生成交互式 API 文档可测试性允许直接在文档中测试 API 端点代码生成支持多种语言的客户端和服务端代码生成Swagger 核心组件组件输入输出适用阶段Swagger Editor手动编写 YAML/JSON实时预览的 API 文档API 设计阶段Swagger UIOpenAPI 文件交互式网页文档开发/测试阶段Swagger CodegenOpenAPI 文件客户端/服务端代码前后端协作阶段组件协作流程图Swagger Editor设计API ↓ OpenAPI 规范文件YAML/JSON ↓ Swagger UI展示文档 或 Swagger Codegen生成代码Swagger 核心组件详解1. Swagger EditorSwagger Editor 是基于浏览器的可视化编辑器用于编写和实时预览 OpenAPI 规范YAML/JSON 格式。Swagger Editor 提供语法高亮、自动补全和错误校验。Swagger Editor 代码生成、保存和导出功能现已加入 SmartBear API Hub访问地址https://try.platform.smartbear.com/new-organization。使用场景快速设计 API 原型学习 OpenAPI 规范语法访问在线编辑器 Swagger EditorSwaggerEditor输入以下 YAML 代码定义一个简单的 GET /users 接口实例span stylecolor: green;openapi: 3.0.3info:title: RUNOOB 用户管理系统version: 1.0.0paths:/users:get:summary: 获取用户列表responses:200:description: 成功返回用户列表content:application/json:schema:type: arrayitems:type: objectproperties:id:type: integername:type: string右侧将实时渲染出 API 文档和交互式 UI。Swagger UISwagger UI 将 OpenAPI 规范转换为可视化交互式文档支持直接在浏览器中测试 API。Swagger UI 会自动生成请求示例、响应模型和调试界面。Swagger UI: REST API Documentation Tool | Swagger UI使用场景团队共享 API 文档前端开发者调试接口集成示例以 Node.js 为例,安装依赖npm install swagger-ui-express swagger-jsdoc创建 swagger.js 配置文件实例const swaggerJSDoc require(swagger-jsdoc);const options {definition: {openapi: 3.0.0,info: { title: 用户API, version: 1.0.0 },},apis: [./routes/*.js], // 扫描路由文件中的注释};const swaggerSpec swaggerJSDoc(options);module.exports swaggerSpec;在 Express 中挂载 UI实例const express require(express);const swaggerUi require(swagger-ui-express);const swaggerSpec require(./swagger);const app express();app.use(/api-docs, swaggerUi.serve, swaggerUi.setup(swaggerSpec));访问 http://localhost:3000/api-docs 查看文档。Swagger CodegenSwagger Codegen 根据 OpenAPI 规范自动生成客户端 SDK如 Java、Python或服务端桩代码如 Spring、Flask。Swagger Codegen 支持自定义模板。下载页面API Code Client Generator | Swagger Codegen使用场景快速生成 API 调用的客户端代码服务端接口自动化开发操作示例命令行生成 Java 客户端, 下载 Swagger Codegen CLIwget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar生成代码java -jar swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l java \ -o ./petstore-api-clientSwagger Hub可选扩展Swagger Hub 是 Swagger 的云端平台提供协作设计、版本管理和托管文档。Swagger Hub 支持团队协作和 API 生命周期管理。使用场景企业级 API 项目管理需要在线协作的分布式团队