什么是OpenAPI（Swagger）？请求简明易懂的技术讲解

什么是OpenAPI？ #

它就是一套标准化的API描述规范——用机器和人都能看懂的格式（通常是YAML或JSON），把你的API的所有细节写进一份文件里。这份文件就像API的“标准化说明书”，不管是开发、测试还是运维，或者是自动化工具，都能通过它快速搞懂API的全部规则。

核心作用（为什么要用它？） #

别管那些高大上的术语，实际好处就这几个：

• 前后端开发不用反复扯皮接口细节：后端写完这份文件，前端直接看，不用追着问“这个字段是字符串还是数字？”“接口返回什么状态码？”
• 自动生成API文档：不用手动写HTML或Markdown文档，工具（比如Swagger UI、Redoc）读这份文件就能直接生成好看的交互式文档，还能在线测试接口。
• 自动生成客户端SDK：比如前端要调用API，工具能直接根据这份文件生成JavaScript/TypeScript调用代码；移动端能生成iOS/Android的SDK，不用手动写请求逻辑。
• 自动化测试：测试工具读这份文件，能自动生成测试用例，验证接口是否符合定义的规则。
• 对接网关、监控等工具：API网关可以直接读取这份文件，自动配置路由、限流、认证规则；监控工具能自动识别API，统计调用量、错误率。

核心组成部分（这份“说明书”里都写什么？） #

挑最关键的几个部分说，搞懂这些就摸透了核心：

• openapi：必须指定的版本号（比如3.0.3、3.1.0），工具靠它来解析文件格式，不同版本语法有细微差别。
• info：API的基本信息，比如名称、版本号、简短描述，相当于API的“名片”。
• servers：API部署的地址，比如测试环境https://test-api.example.com/v1、生产环境https://api.example.com/v1，调用时直接用这里的地址。
• Paths：核心中的核心！所有API接口的定义都在这里。比如/users这个路径，下面会对应GET（查用户列表）、POST（创建用户）等HTTP方法，每个方法里要写：
  • Parameters：接口的参数，比如路径里的/users/{userId}中的userId，或者查询参数/users?page=1里的page，要说明参数位置（路径、查询、请求头）、类型、是否必填。
  • Request Body：POST/PUT请求时要传的数据（比如创建用户时的name、email），要定义数据结构、字段类型、格式约束（比如邮箱格式）。
  • Responses：接口返回的内容，比如200成功时返回的JSON结构，404找不到时的错误信息，每个状态码对应的数据格式都要写清楚。
• Components：可复用的“零件库”。比如多个接口都要用到的User对象结构，或者重复用的认证方式，定义在这里，其他地方直接引用就行，不用重复写代码。
• Security：API的认证规则，比如用JWT Token还是API Key，要说明认证信息怎么传（比如放在请求头的Authorization里）。

极简示例（看一眼就懂） #

下面是个最简化的OpenAPI文件示例，用YAML写的：

openapi: 3.0.3
info:
  title: 用户管理API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users/{userId}:
    get:
      summary: 根据ID获取单个用户
      parameters:
        - name: userId
          in: path
          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
        name:
          type: string
        email:
          type: string
          format: email

简单解释：

• 指定了用OpenAPI 3.0.3版本，API叫“用户管理API”，版本1.0.0
• 服务器地址是https://api.example.com/v1
• 定义了GET /users/{userId}接口：路径参数userId是必填整数，成功返回200时，返回的是components里定义的User对象（包含id、name、邮箱格式的email字段）

一句话总结核心 #

OpenAPI的本质就是用标准化格式，把API的“输入、输出、规则”全部写清楚，让人和机器都能无歧义地理解API——它不是API本身，而是API的“说明书”，但这份说明书能帮你省去大量重复工作，让API开发、对接、维护更高效。

内容的提问来源于stack exchange，提问作者user18392765