什么是 Open API Specification

于 2024-08-02 19:36:52 发布
阅读量707 收藏 20
点赞数 11
分类专栏： OData 文章标签： OData
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/m0_55213370/article/details/140878798
版权

什么是 Open API Specification

Open API Specification（简称 OAS），是一种标准化的语言，用于定义 RESTful API 的规范。RESTful API 是通过 HTTP 协议进行通信的接口，开放 API 则是让不同应用系统之间能够通过 API 进行交互。OAS 的出现，使得 API 的设计、文档编写和测试更加规范化和自动化。

OAS 在社区的支持下，逐渐成为描述 API 的事实标准。它的前身是 Swagger，虽然名称变了，但是它们的使命是一致的：通过统一的格式描述 API，避免了 API 文档混乱、版本不一致等问题。

为了更容易地理解 OAS，可以通过一个具体的例子来说明。

设想一个图书管理系统，这个系统允许用户添加、获取、更新和删除图书信息。我们将使用 Open API Specification 来描述这些操作。

示例：图书管理系统 API
openapi: 3.0.0
info:
  title: 图书管理系统 API
  description: 一个简单的图书管理系统的 API
  version: 1.0.0
servers:
  - url: http://api.books.com/v1
paths:
  /books:
    get:
      summary: 获取所有图书
      description: 返回系统中的所有图书
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
    post:
      summary: 添加一本图书
      description: 创建一个新的图书条目
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewBook'
      responses:
        '201':
          description: 创建成功
  /books/{id}:
    get:
      summary: 获取特定图书
      description: 根据 ID 获取图书详情
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: 图书未找到
    put:
      summary: 更新特定图书
      description: 根据 ID 更新图书信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewBook'
      responses:
        '200':
          description: 更新成功
        '404':
          description: 图书未找到
    delete:
      summary: 删除图书
      description: 根据 ID 删除图书条目
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 删除成功
        '404':
          description: 图书未找到
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer
    NewBook:
      type: object
      properties:
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer

这个例子展示了一个图书管理系统的 API。接下来，深入探讨其各个部分：

  1. openapi: 3.0.0：
    表示使用的是 Open API Specification 3.0.0 版本。

  2. info：
    包含了 API 的基础信息，如标题、描述、版本号等。

  3. servers：
    描述了 API 的服务器 URL。在这个例子中，http://api.books.com/v1 是 API 的访问地址。

  4. paths：
    定义了 API 路径及其具体操作。有两个主要路径：/books 和 /books/{id}。每个路径下定义了操作（GET、POST、PUT、DELETE 等），每种操作都有自己的描述、请求参数和响应信息。

  5. components：
    定义了 API 使用的复用模式。在这个例子中，有两个模式：Book 和 NewBook。Book 描述了完整的图书信息，而 NewBook 描述了新创建图书的信息。

让我们仔细看看 /books 路径下的操作：

  • GET /books：
    该操作获取所有图书。响应是一个包含图书对象的数组，响应码是 200 表示成功。

  • POST /books：
    该操作用于添加一本新图书。请求体需要包含新图书的信息，格式为 JSON。响应码 201 表示创建成功。

再看 /books/{id} 路径下的操作：

  • GET /books/{id}：
    该操作获取特定图书的信息。请求参数 id 表示图书的唯一标识，响应码 200 表示成功，404 表示图书未找到。

  • PUT /books/{id}：
    该操作更新特定图书的信息。请求参数 id 和请求体（新图书信息）是必须的，响应码 200 表示更新成功，404 表示图书未找到。

  • DELETE /books/{id}：
    该操作删除特定图书。请求参数 id 是必须的，响应码 204 表示删除成功，404 表示图书未找到。

除了规范 API 的设计和文档外，OAS 还能帮助生成客户端和服务器代码，甚至可以自动化测试。API 的定义越详细，自动化的程度越高，开发和维护的效率也越高。

真实世界的应用：Twitter API

为了让这个概念更加具体，我们可以看看真实世界中如何应用 OAS。Twitter 提供了一个非常成熟的 API，可以帮助开发者访问 Twitter 的功能，比如发推文、读取用户时间线等。Twitter 的 API 有详细的文档，而且本身就是使用 Open API Specification 描述的。

比如，获取 Twitter 用户时间线的 API：

openapi: 3.0.0
info:
  title: Twitter API
  description: 这个 API 允许应用程序与 Twitter 的功能进行交互
  version: 2.0.0
servers:
  - url: https://api.twitter.com/2
paths:
  /users/{id}/tweets:
    get:
      summary: 获取用户时间线
      description: 返回指定用户的推文时间线
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: 用户的唯一标识
        - name: max_results
          in: query
          required: false
          schema:
            type: integer
            description: 返回的最大推文数量
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tweet'
        '404':
          description: 用户未找到
components:
  schemas:
    Tweet:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
        created_at:
          type: string
          format: date-time

从这个示例中，我们可以看到 Twitter 是如何通过 OAS 描述其 API 的。无论是路径参数 id 还是 query 参数 max_results，都清楚地定义了它们的位置、是否必须以及数据类型。同时，响应部分通过引用模式 Tweet 来定义推文的结构。

事务性和一致性

另一个值得探讨的概念是事务性和一致性。对于像金融系统或者库存管理系统这类需要事务确保数据一致性的系统，API 的设计和规范尤为重要。

假设我们管理一个电子商务系统，其中一个 API 用于处理订单。订单系统需要确保在多个操作步骤中，数据的一致性和可靠性。我们可以借助 OAS 和事务管理技术，通过定义好每个步骤的 API 和处理逻辑，确保整个事务的完整性。

例子：订单管理系统

openapi: 3.0.0
info:
  title: 订单管理系统 API
  description: 这个 API 处理电子商务订单
  version: 1.0.0
servers:
  - url: http://api.orders.com/v1
paths:
  /orders:
    post:
      summary: 创建订单
      description: 创建一个新订单并开始事务
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewOrder'
      responses:
        '201':
          description: 创建成功，返回订单 ID
  /orders/{id}:
    put:
      summary: 更新订单状态
      description: 更新特定订单的状态以反映事务的几个步骤
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderStatus'
      responses:
        '200':
          description: 更新成功
        '404':
          description: 订单未找到
components:
  schemas:
    NewOrder:
      type: object
      properties:
        customerId:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      properties:
        productId:
          type: string
        quantity:
          type: integer
    OrderStatus:
      type: object
      properties:
        status:
          type: string
          enum: [pending, confirmed, shipped, delivered, canceled]

例如，一个新订单创建的流程可能包含以下步骤：

  1. 从客户账户中扣款。
  2. 减少库存。
  3. 通知仓库准备发货。
  4. 更新订单状态为 confirmed。

在这个过程中，我们需要确保每一步都成功才能进入下一步。如果某步骤失败，需要执行回滚操作以保持系统内数据的一致性。

OAS 使得各步骤的接口规范化，便于各模块之间的集成，同时也容易被测试和维护。通过这种方式，OAS 可以帮助确保复杂事务性操作的一致性和可靠性。

安全性

讨论 API 规约，安全性是一个绕不开的话题。OAS 提供了多种机制来描述和实现安全性。

在 OAS 中，我们可以定义安全需求，如 OAuth2、API Key 等。假设我们的图书管理系统需要用户登录，并使用 Bearer Token 进行身份验证：

openapi: 3.0.0
info:
  title: 安全的图书管理系统 API
  description: 这个 API 使用 Bearer Token 进行身份验证
  version: 1.0.0
servers:
  - url: http://api.securebooks.com/v1
paths:
  /books:
    get:
      summary: 获取所有图书
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT  # 可选，指定 JWT 格式
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer

在这个示例中，securitySchemes 定义了 bearerAuth 作为认证方式，并指定在 GET /books 路径下的操作需要这种认证。通过这样的定义，我们可以确保只有通过身份验证的用户才能访问 API。

安全性不仅仅是身份验证，还有比如数据加密、输入校验、防止 CSRF 和 XSS 等多种手段。通过 OAS，可以更加清晰和详细地定义这些安全要求，使 API 开发和使用更加安全可信。

版本控制

API 的版本控制也是一个重要的概念。在实际应用中，API 需要不断演进和更新，但又必须保证旧版的兼容性。OAS 支持通过版本号来管理 API 的不同版本。

假设我们的图书管理系统从 1.0 版本升级到 2.0 版本，新版本添加了新的字段和路径。我们可以这样定义：

openapi: 3.0.0
info:
  title: 图书管理系统 API
  description: 图书管理系统的不同版本 API
  version: 2.0.0
servers:
  - url: http://api.books.com/v2
paths:
  /books:
    get:
      summary: 获取所有图书
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
  /books/{id}:
    get:
      summary: 获取特定图书
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer
        genre:  # 新增字段
          type: string

通过版本号和路径的区分，新老版本的 API 可以同时存在，保证了系统的兼容性和灵活性。这在实际开发中非常重要，可以避免由于 API 的变动导致的不可预见的问题。

总结

OAS 是一个强大的工具，用于描述 RESTful API 规范。它通过对 API 的详细描述，使得 API 的设计、文档编写、测试和使用更加规范化和自动化。通过具体的例子，如图书管理系统、Twitter API 和订单管理系统，可以清楚看到 OAS 在实际应用中的强大功能。不论是事务性、一致性、安全性还是版本控制，OAS 都提供了强大的支持，使 API 开发更加高效和可靠。

西门吹雪在编程
关注
  • 11
    点赞
  • 踩
  • 20
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
OpenProtocol_Specification_R_2_10_0_9836 4415 01.pdf
08-18
阿特拉斯电枪开放式协议
OpenProtocol_Specification_.pdf
11-08
PF4000开放协议 Atlas_OpenProtocol_开放协议报文详解
OpenProtocol_Specification 2.7.pdf
08-13
Open Protocol is an interface for building applications for remote control or data subscription of controllers. It is platform independent and can be implemented on Linux, PLC, printers, and all Windows platforms for example.
阿特拉斯拧紧机（Atlas）开放性协议 OpenProtocol_Specification_通讯.pdf
06-27
阿特拉斯拧紧机（Atlas）开放性协议 OpenProtocol_Specification_通讯.pdf
Open Core Protocol Specification
03-25
The Open Core Protocol™ (OCP™) delivers the only non-proprietary, openly licensed, core-centric protocol that comprehensively describes the systemlevel integration requirements of intellectual property (IP) cores. While other bus and component interfaces address only the data flow aspects of core communications, the OCP unifies all inter-core communications, including sideband control and test harness signals. The OCP's synchronous unidirectional signaling produces simplified core implementation, integration, and timing analysis.
Open API Specification
01-02
Open API Specification，中文称之为开放API规范，是业界广泛使用的一种API接口描述标准，也常被称为Swagger规范。OAS3.0-rc2是其最新修订版本的候选发布版本2，而"共通性应用程式介面规范附件_OAS3.0-rc2_v0620"则...
Open Mobile API specification 中文版
10-23
Open Mobile API specification 中文版 有道翻译 翻译的不咋地，但总比看英文的强点
Open Mobile API Specification中文版翻译
最新发布
04-25
### Open Mobile API 规范 V2.052 知识点详解 #### 一、概述 《开放移动API规范》（以下简称“规范”）是一份详细的文档，它旨在为移动设备上的安全元素（Secure Element, SE）提供一套标准化的接口定义。这份中文...
OpenRTB-API-Specification-Version-2-3
11-06
下图摘自 OpenRTB_API_Specification_Version2.0_FINAL 半壁江山 生态系统总的来说分为2个部分，卖方和买方。 卖方：媒体，即拥有广告资源的人，如新浪这个媒体有很多用户访问，有很多广告位。 买方：广告主，即...
OpenProtocol-MTF6000
01-15
阿特拉斯控制器MTF6000开放式协议资料；对应TCPIP；对应报文格式
OpenRTB_API_Specification_Version_2_3_1.pdf
10-25
OpenRTB_API_Specification_Version_2_3_1.pdf，openrtb开放协议
OpenAPI Specification
bruce的技术博客
10-20 438
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service with
UEFI open protocol详解
Helping BIOSer become Awesome!
02-28 7034
openProtocol 用于查询指定的Handle中是否支持指定的Protocol,如果支持，则打开Protocol，否则返回错误代码。下面OpenProtocol服务的函数实现。 CoreOpenProtocol(  IN  EFI_HANDLE  UserHandle,  IN  EFI_GUID  *Protocol,  OUT VIOD     **Interface OPTIO
OpenAPI Specification 3.0 开放API规范
大西瓜的博客
09-10 2916
OpenAPI Specification 3.0 开放API规范 版本 3.0.0 介绍 OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好，那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。 如果您遵循 OpenAPI 规范来定义您的 API，那么您就可以用文档生成工具来展示您的 A
Openprotocol协议解析1
热门推荐
sgmcumt的博客
10-24 1万+
简介 开放协议是远程通信接口。它是独立于系统平台的，可以在Linux、PLC、打印机和所有Windows上实现。 开放协议同时支持串行和以太网连接。 本文是以阿特拉斯扭矩枪为例，说明开放协议的使用。 本文用到的术语表。 术语 定义 控制器（Controller） 支持开发协议的服务器 接收器（Integrator） 接收器可以为电脑、PLC或打印机。接收器安装使用开放协议的应用...
OpenRTB API规格2.4：实时竞价技术标准
"OpenRTB-API-Specification-Version-2-4-FINAL.pdf 是一份关于OpenRTB（Real-Time Bidding）API规格的详细文档，该文档由IAB（Interactive Advertising Bureau）技术实验室发布，旨在定义一个开放的协议，用于自动...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值