OpenAPI：基于 REST API 的接口规范

作者：马育民 • • 阅读：10039

介绍

OpenAPI Specification（OAS，OpenAPI 规范），前身叫做 Swagger Specification。

它是一套与编程语言无关、标准化的 REST API 描述规范，使用 JSON/YAML 文件定义接口所有信息。

一句话理解

OpenAPI 是一套 机器可读、人也可读 的 REST API 标准化 接口描述 规范

发展历史

  1. Swagger

    • 早期：规范名称（Swagger Spec）
    • 现在：工具生态（Swagger UI、Swagger Editor、Swagger Codegen）

  2. OpenAPI

    • 2015年，Swagger Spec 捐赠给 Linux 基金会，更名为 OpenAPI Specification
    • OpenAPI 2.0 = 旧版 Swagger 2.0
    • OpenAPI 3.x（主流：3.0.3 / 3.1.0） 全新版本，语法有较大改动，推荐新项目使用 OAS3

注意

OpenAPI≠Swagger；Swagger是配套工具，OpenAPI是规范标准。

作用

  1. 统一接口规范（API First 基石）
    前后端、服务之间先定义 OpenAPI 文件，再开发，避免口头沟通不一致。

  2. 自动生成文档
    输入规范文件 → Swagger UI / ReDoc 渲染交互式在线接口文档，支持在线调试。

  3. 代码自动生成
    根据 OpenAPI 文件，一键生成：前端TS/JS客户端、Java/Python/Go服务端骨架、接口Mock服务。

  4. 自动化测试、网关接入、接口校验
    API网关（Kong、APISIX、SpringCloud Gateway）、测试工具、Postman均可导入OpenAPI文件。

  5. 接口Mock服务
    直接基于规范模拟返回数据，前端可独立开发，无需等待后端完成。

版本

版本 备注 兼容性
OpenAPI 2.0（Swagger2） 旧项目大量遗留，语法老旧 不推荐新项目
OpenAPI 3.0.x 企业最通用稳定版本 主流框架全面支持
OpenAPI 3.1.x 最新标准，支持 JSON Schema 2020-12，类型能力更强 部分老旧工具兼容差

国内选择

SpringBoot、FastAPI、NestJS 生态首选：OpenAPI 3.0.3

规范文件结构

文件后缀：.yaml / .yml / .json

# 必填：指定规范版本
openapi: 3.0.3
# 接口文档元信息
info:
  title: 用户管理API
  description: 用户增删改查接口文档
  version: 1.0.0
  contact:
    name: 开发团队
    email: dev@xxx.com
# 服务地址列表（多环境：测试/生产）
servers:
  - url: http://localhost:8080/api
    description: 本地开发环境
# 全局路径：所有接口定义
paths:
  /user/{id}:
    get:
      summary: 根据ID查询用户
      description: 获取单个用户详情
      parameters:
        - name: id
          in: path # path/query/header/cookie
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
# 复用组件：模型、请求体、鉴权方案（抽离复用，避免重复代码）
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
# 全局鉴权配置
security:
  - BearerAuth: []

主要字段解释

  1. openapi：声明OAS版本，3.0.3
  2. info：文档标题、版本、描述、联系人、许可证
  3. servers：接口基础URL，支持多环境
  4. paths【核心】
    定义所有接口路径、请求方式（GET/POST/PUT/DELETE）
    • summary：简短接口名称
    • description：详细说明
    • parameters：参数（路径参数、查询参数、请求头）
    • requestBody：POST/PUT 请求体
    • responses：各个状态码返回数据
  5. components【复用中心】
    • schemas：数据模型（DTO、实体类）
    • securitySchemes：认证方式（Token、Basic、ApiKey、OAuth2）
    • requestBodies、parameters：公共参数抽取
  6. security：全局身份认证策略

优势与局限

✅ 优势

  1. 跨语言通用，不绑定任何开发框架
  2. API-First 标准契约，微服务协作标准
  3. 文档、代码、测试、网关全链路打通
  4. 支持导入Postman、ApiPost、Apifox

⚠️ 局限

  1. 仅适用于 RESTful HTTP API；不支持RPC(gRPC)、WebSocket、消息队列接口
  2. YAML手写繁琐，大型项目建议由框架自动生成
  3. 复杂业务校验逻辑无法完整描述，只能定义数据结构

常用配套工具生态

1. 文档展示

  • Swagger UI：交互式文档，可以直接在线发起请求（最流行）
  • ReDoc：简洁静态文档，适合对外开放API
  • Scalar：新一代轻量化OpenAPI文档UI（替代Swagger UI趋势）

2. 编辑器

  • Swagger Editor（网页在线编写yaml）
  • VSCode 插件：OpenAPI Preview、Swagger Lint

3. 代码生成

  • OpenAPI Generator（官方推荐，替代旧swagger-codegen）
    支持生成 Java/SpringBoot、Python FastAPI、TS Axios客户端、Go、C# 等
  • 前端：openapi-typescript 生成TypeScript类型

4. Mock服务

  • Prism、Mock Service Worker、WireMock
    读取OpenAPI规范，启动模拟接口服务

5. 校验工具

  • Spectral：OpenAPI规范静态检查，规范评审、约束校验

主流框架集成

Java(SpringBoot)

  • SpringDoc OpenAPI 3（替代老旧springfox-swagger2）
    自动扫描Controller生成OpenAPI3规范，内置SwaggerUI

    ❌ 不要再使用 springfox（Swagger2），停止维护、兼容性差

Python

  • FastAPI：原生自动生成OpenAPI，开箱即用
  • Flask：Flask-RESTX

Node.js

NestJS @nestjs/swagger、Express + swagger-jsdoc

原文出处：/show_1GW3n3vSgjUN.html

吉ICP备15003043号