OpenAPI是什么？从入门到精通

一个幽默的程序员

已于 2025-06-05 15:38:26 修改

阅读量934

点赞数 18

文章标签： openapi api apifox

于 2025-06-05 15:38:04 首次发布

本文链接：https://blog.csdn.net/gdjnrc_com/article/details/148451529

版权

OpenAPI 规范（即OAS）是一种与编程语言无关的API描述标准。它使计算机和人类用户都能够识别和理解服务功能，无需额外的文档、源代码或网络流量分析。OAS消除了API调用的不确定性，类似于接口描述如何简化底层编程。通过OpenAPI，开发者可以快速了解API的工作原理，促进前后端高效协作。OpenAPI规范通常使用YAML或JSON格式编写，便于跨平台和工具间共享。
在这里插入图片描述

OpenAPI的发展历程

OpenAPI规范的发展历程可以追溯到2010年，经历了从Swagger到OpenAPI的演变：

2010年：Swagger项目启动，旨在简化RESTful API的文档生成
2015年：Swagger规范被捐赠给Linux基金会下的OpenAPI Initiative
2016年：OpenAPI规范2.0发布（基于Swagger 2.0）
2017年：OpenAPI规范3.0发布，带来重大改进
2021年：OpenAPI规范3.1发布，进一步完善和扩展功能

如今，OpenAPI已成为行业标准，被众多企业和开源项目广泛采用。

API优先开发：现代软件工程的最佳实践

在项目开发中，“API优先”（API-First）已成为业界公认的最佳实践。这种方法要求在编写任何代码前，先设计和定义API接口文档。一份完善的接口文档应包含：

接口的命名规则和URL路径设计
请求方法、参数和头信息
响应状态码、数据结构和示例
错误处理机制和安全认证方式

采用API优先开发有以下显著优势：

提高开发效率：前后端可以并行开发，减少等待时间
减少沟通成本：明确的API契约减少团队间的误解
提升产品质量：早期发现设计问题，避免后期大规模重构
便于测试和集成：可以基于API文档提前编写测试用例

API文档是整个代码开发的基础，通过规范的接口定义来指导实现，能够构建出更加稳定高效的系统。

深入理解OpenAPI规范

OpenAPI的规范源自Swagger，经过Reverb Technologies和SmartBear等公司多年维护，现已发展成为独立而完善的标准。想深入了解，推荐阅读：OpenAPI规范（中文版）

OpenAPI规范的语言无关性确保了其通用性和普及性。通常通过JSON或YAML这类通用格式进行交换，保证跨平台兼容。
在这里插入图片描述

OpenAPI 3.0核心组件详解

以OpenAPI 3.0.1为例，一份完整的OpenAPI文档通常包含以下核心组件：

对象	描述	是否必需
OpenAPI Object	整个OpenAPI文档对象	是
Info Object	描述文档信息的对象	是
Paths Object	描述接口路径的对象	是
Components Object	描述可复用组件的对象	否
Tag Object	对路径进行分组的对象	否
ExternalDocs Object	拓展文档对象	否
Security Object	安全性对象	否
Servers Object	描述服务端的对象	否

OpenAPI文档示例解析

Info Object示例：

openapi: 3.0.1
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/xxx/books/1.0.0
info:
  version: "1.0.0"
  title: home-iot-api
  description: The API for the EatBacon IOT project
  contact:
    name: API Support Team
    email: support@example.com
    url: https://www.example.com/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

Paths Object示例：

paths:
  /devices:
    get:
      tags:
        - Device
      description: returns all registered devices
      operationId: getDevices
      parameters:
        - in: query
          name: skip
          description: number of records to skip
          schema:
            type: integer
            format: int32
        - in: query
          name: limit
          description: max number of records to return
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: All the devices
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri
                  example: 'http://10.0.0.225:8080'
        '400':
          description: Bad request
        '500':
          description: Internal server error