OpenAPI：基于 REST API 的接口规范-马育民老师

# 介绍

**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`

```yaml
# 必填：指定规范版本
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](https://www.malaoshi.top/show_1GW3n3uHkF2M.html "Swagger UI")**：交互式文档，可以直接在线发起请求（最流行）
- **ReDoc**：简洁静态文档，适合对外开放API
- **Scalar**：新一代轻量化OpenAPI文档UI（替代Swagger UI趋势）

### 2. 编辑器
- [Swagger Editor](https://www.malaoshi.top/show_1GW3n3uHkF2M.html "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

原文出处：http://www.malaoshi.top/show_1GW3n3vSgjUN.html