由于API对于我们的软件运行方式至关重要，因此记录我们的API对于确保我们大型IT组织中的每个人都了解正在发生的事情至关重要，这就是我们使用OpenAPI来帮助记录API规范的原因。

在本文中，我将向你介绍OpenAPI规范和API-First开发原则。

OpenAPI规范

OpenAPI规范始于Swagger规范，经过Reverb Technologies和SmartBear等公司多年的发展，OpenAPI计划拥有该规范（捐赠之后），OpenAPI Initiative在GitHub上托管社区驱动的规范。

规范是一种与语言无关的格式，用于描述RESTful Web服务，应用程序可以解释生成的文件，这样才能生成代码、生成文档并根据其描述的服务创建模拟应用。

什么是API优先开发？

应用程序向云环境这一演变趋势为更好地集成服务和增加代码重用提供了机会，只要拥有一个接口，然后通过该接口，其他服务的应用程序就可以与你的应用程序进行交互，这是向其他人公开你的功能，但是，开发API却不应该是在开发后才公开功能。

API文档应该是构建应用程序的基础，这个原则正是API-First(API优先)开发的全部内容，你需要设计和创建描述新服务与外部世界之间交互的文档，一旦建立了这些交互，就可以开发代码逻辑来支持这些交互。让我们来看看这种方法带来的好处。

API-First如何使您的组织受益

当你的组织从API文档开始时，这允许团队在开发过程中更快地开始彼此交互。API文档是应用程序与使用它的人之间的合同。

内部开发可以在API合同背后进行，而不会干扰使用它的人的努力，计划使用你的应用程序的团队可以使用API规范来了解如何与你的应用程序进行交互，甚至在开发之前。他们还可以使用该文档创建用于测试其应用程序的虚拟服务。

OpenAPI文档的剖析

该规范的当前版本是3.0.1版，并在OpenAPI GitHub存储库中进行了详细记录。但是，如果你像我一样，我更喜欢看一个规范的例子，而不是通过描述文档描述每个可能的部分的明确的技术细节。

让我们看一个描述服务API的简单API文档，它允许用户创建，修改，检索和删除用户首选项。您可以在SwaggerHub上完整地查看此API 。

OpenAPI文档有三个必需的部分或对象：

1. openapi - OpenAPI规范版本的语义版本号

2. info - 有关API的元数据

3. paths - API的可用路径和操作

你可以根据需要包含其他对象。其他对象包括安全性，服务器，标签和组件。

openapi: 3.0.1info: version:"1.0.0" title: 用户指导API

description: 这是一个支持用户设置的创建，修改，检索和删除。

<p>

openapi对象声明了用于文档的规范的版本。该版本对于用户理解文档的结构至关重要，更重要的是，对于可能为了验证目的而获取文档或创建虚拟服务的任何工具，info对象提供有关API本身的基本信息。标题和版本是必填字段，我们可以选择包含其他信息，例如说明，联系和许可信息。

路径对象

paths路径对象是API文档的核心。此对象详细说明了可与应用程序交互的路径，可用的方法以及这些交互包含的内容的详细信息。该对象包括请求参数和预期结果：

paths:

/preference:

  get:

    summary: 根据ID发现用户设置

    description: 返回用户设置

    operationId: getPreferenceById

    parameters:

    - name: id

      in: query

      description: 这是返回一个用户设置的ID

      required: true

      schema:

        type: string

    responses:

      '200':

        description: 请求成功

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/Preference'

      '400':

        description: 无效 ID

      '404':

        description: 用户设置没有发现

<p>

上面的摘录描述了按ID检索用户设置的GET请求路径，这些属性大多是不言自明的。值得注意的是HTTP 200响应的模式。$ ref属性引用文件中其他位置的对象，它是用于多个路径的描述：

#/components/schemas/Preference的结构如下：

components:

schemas:

  Preference:

    type: object

    required:

    - userId

    - preferenceName

    - status

    properties:

      userId:

        type: string

        format: uuid

      preferenceName:

        type: string

      preferenceValue:

        type: string

      status:

        type: string

        description: Preference Status

        enum:

        - test

        - enabled

        - disabled

        - delete

<p>

在另外一个地方定义组件并引用它，这种方式能让我们重用相同的定义并使我们的OpenAPI合同更易于管理。

在swaggerhub有在线编辑器可以体验。