OpenAPI 规范（OAS）介绍 - Bearalise

当日所学
Word count: 1.1k   |   Reading time≈ 4 min

背景

作为一名开发者，都需要编写程序的 API 文档。现代开发框架，都需要API的协作，有时完成一个操作，需要调用多个API才能完成，所以，一个好的 API 文档能够大大提高协作效率，降低沟通成本。为解决API文本规范的问题，我们聊聊如何使用 OpenAPI 构建 HTTP 接口文档。

OpenAPI 规范（OAS）介绍

OpenAPI 是规范化描述 API 领域应用最广泛的行业标准，由 OpenAPI Initiative(OAI) 定义并维护，同时也是 Linux 基金会下的一个开源项目。通常我们所说的 OpenAPI 全称应该是 OpenAPI Specification(OpenAPI 规范，简称 OSA)，它使用规定的格式来描述 HTTP RESTful API 的定义，以此来规范 RESTful 服务开发过程。使用 JSON 或 YAML 来描述一个标准的、与编程语言无关的 HTTP API 接口。OpenAPI 规范最初基于 SmartBear Software 在 2015 年捐赠的 Swagger 规范演变而来，目前最新的版本是 v3.1.1。本文参考了apifox 发布的一个 中文版。

OpenAPI 规范基本信息

文档结构

一份 OpenAPI 文档可以是单个文件也可以被拆分为多个文件， 连接的部分由用户自行决定。在后一种情形下，必须如 JSON Schema 中定义的那样使用 $ref 字段来相互引用。

推荐将根 OpenAPI 文档命名为openapi.json 或 openapi.yaml。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
openapi: 3.0.0
info:
  title: 示例 API
  description: 这是一个简单的示例 API 文档。
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: 主服务器

paths:
  /users:
    get:
      summary: 获取用户列表
      description: 返回所有用户的列表。
      responses:
        '200':
          description: 成功获取用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

  /users/{userId}:
    get:
      summary: 获取特定用户
      description: 根据用户ID返回特定用户的信息。
      parameters:
        - name: userId
          in: path
          required: true
          description: 用户的唯一标识符
          schema:
            type: string
      responses:
        '200':
          description: 成功获取用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 未找到用户

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          description: 用户ID
        name:
          type: string
          description: 用户名
        email:
          type: string
          format: email
          description: 用户电子邮箱地址

以上为示例，具体语法可参考官网，只需要大概了解就可以了，实际上日常我们会搭建工具，自动生成此文档。

另外还推荐访问 OpenAPI Map 网站来掌握 OpenAPI 规范，该网站以思维导图的形式展现规范的格式以及说明。

相关工具

现在我们知道了 OpenAPI 规范，接下来介绍一下OpenAPI.Tools 的网站，它分类整理并记录了社区围绕 OpenAPI 规范开发的流行工具。

可以看到列表中有很多分类，在我们日常开发中，最经常使用的有三类：

文档编辑器

文本编辑器推荐使用在线的 Swagger Editor，能够实现格式校验和实时预览 Swagger 交互式 API 文档功能，效果如下图所示：

Mock 服务器

当我们使用 OpenAPI 规范来进行接口开发时，往往采用文档先行的策略，也就是前后端在开发代码前，先定义好接口文档，再进行代码的编写。此时前端如果想测试接口可用性，而后端代码还没有编写完成，Mock 服务器就派上用场了。Mock 服务器能够根据所提供的 OpenAPI 接口文档，自动生成一个模拟的 Web Server。使用 Mock 服务器能够轻松模拟真实的后端接口，方便前端同学进行接口调试，这方面的SaaS服务很多，可以试试 APIGit 。

代码生成器

还有一种很实用的工具是代码生成器，代码生成器有两种类型：一种是从代码/注释生成 OpenAPI 文档，另一种是从 OpenAPI 文档生成代码。可以试试 Swagger Codegen 和 OpenAPI Generator 这类工具，支持几乎所有主流编程语言。

作者：Bearalise
出处：https://blog.952005.xyz/2025/02/17/openapi-introduction/
版权：本文版权归作者所有
转载：欢迎转载，但未经作者同意，必须保留此段声明，必须在文章中给出原文链接。

请我喝杯咖啡吧~

支付宝
微信