使用开源跨平台工具设计和记录 API

Insomnia Designer 通过提供协作工具来组织、维护和验证 API 规范，使规范优先开发更易于访问。

图片来源

Opensource.com

在软件即服务 (SaaS) 和基于服务的架构领域，公司维护数十甚至数百个 API 并不罕见，这些 API 通常跨越多个团队、编程语言和环境。这种可变性使得从高层次了解正在发生的事情以防止更改产生负面影响变得极其困难。

据估计，40% 的大型企业在 API 的安全、扩展或确保性能方面面临挑战。因此，越来越多的公司选择采用“规范优先开发”方法，通过 OpenAPI 等外部格式定义和记录 API。OpenAPI。将这些文档集中存储在一个位置，可以更轻松地在实施之前设计、讨论和批准更改。

在本教程中，您将使用最近发布的 Insomnia Designer 来记录 API、探索它，并使用规范优先方法提出更改。Designer 是一款跨平台开源 REST 客户端，它构建在 Insomnia Core 之上——Insomnia Core 是一款流行的用于与 HTTP 和 GraphQL API 交互的应用程序——旨在通过提供协作工具来组织、维护和验证 API 规范，使规范优先开发更易于访问。本质上，Core 最适合探索和调试 API，而 Designer 最适合设计和记录 API。

在本操作指南中，您将使用 Open Library API 作为基础，以便拥有可供使用的工作示例。您将创建一个最小的 OpenAPI 规范来记录 API，使用 Insomnia Designer 来测试和验证您所做的是正确的，然后使用规范优先方法对 API 进行一些设计更改。

规范优先工作流程

在开始之前，您应该了解采用规范优先工作流程所需的步骤。在规范优先开发中，规范可以处于以下两种状态之一

已发布规范： 准确描述当前已发布 API 的规范
提案规范： 包含需要实施的更改的草案规范

根据这些信息，您可以定义一个用于更改 API 的工作流程

从 API 的已发布规范开始
更改规范以添加或修改行为
审查提案规范以确保设计足够
在代码中实施更改以匹配提案
随 API 一起发布提案规范

现在您已经了解了您要完成的工作的工作流程，请打开 Insomnia Designer 并开始试用。

定义初始规范

由于您还没有 Open Library API 的已发布规范，因此您需要定义一个。

首先从创建菜单创建一个新的空白文档，为其命名，然后单击文档进入设计视图。从这里，您可以开始编辑您的规范。

图片来源

^{（Greg Schier，CC BY-SA 4.0）}

OpenAPI 规范最常以 YAML 格式编写，并且需要四个顶级块才能开始：openapi、info、servers 和 paths。以下示例定义了每个块，并附有有用的注释来描述每个块的用途。此外，paths 块定义了 GET /recentchanges.json 的路由

# Specify that your document is the OpenAPI 3 format
openapi: 3.0.0

# Define high-level metadata for the API
info:
  version: 1.0.0
  title: Open Library API
  description: Open Library has a RESTful API
  
# Specify the base URL the API can be accessed from
servers:
  - url: http://openlibrary.org

# Define operations for the API. This will be where most 
# of the work is done. The first route you'll be defining 
# is `GET /recentchanges.json`
paths:
  /recentchanges.json:
    get:
      summary: Recent Changes

OpenAPI 提供的功能远不止此处可见的功能，例如定义身份验证、响应格式、可重用组件等等的功能。

将上述规范复制到 Insomnia Designer 后，您将看到三列

导航侧边栏（左侧）： 嵌套菜单，使导航较大的文档更容易
规范编辑器（中间）： 用于编辑 YAML 文档的文本编辑器
文档预览： 生成的文档，用于预览规范

图片来源

^{（Greg Schier，CC BY-SA 4.0）}

随意修改规范的不同部分，看看会发生什么。作为一种安全措施，当您做错事时，Insomnia Designer 会提醒您。例如，如果您不小心删除了第 18 行的冒号，则错误面板将显示在编辑器下方。

图片来源

^{（Greg Schier，CC BY-SA 4.0）}

现在您已经定义了一个规范，您可以通过切换到调试模式并向 API 发送真实请求来验证您的定义是否正确。在调试模式下，您可以看到为 GET /recentchanges.json 端点生成了一个路由。单击 URL 旁边的发送按钮以执行请求并在右侧面板中呈现响应。

图片来源

^{（Greg Schier，CC BY-SA 4.0）}

就这样！您已成功验证您创建的 API 规范与生产 API 匹配。现在您可以转到规范优先开发工作流程的下一步并提出更改。

创建提案规范

根据上面概述的工作流程，对您的 API 所做的更改应首先在规范中定义。这有很多好处

规范可以签入中央源代码存储库
更改易于审查和批准
API 以单一、一致的格式定义
避免了不必要的代码更改

继续并对您的 API 提出更改。在调试模式下，我注意到 API 返回了数百个结果。为了提高性能和可用性，将返回的结果数量限制为特定数量将非常有用。一种常见的做法是在 URL 的查询部分接受 limit 参数，因此继续修改您的规范以添加 limit 参数。

在 OpenAPI 中，您可以通过将 parameters 块添加到路由来定义此参数：

# ...
paths:
  /recentchanges.json:
    get:
      summary: Recent Changes
      
      # Add parameter to limit the number of results
      parameters:
        - name: limit
          in: query
          description: Limit number of results
          required: true
          schema:
            type: integer
            example: 1

您可以通过展开预览中的路由并检查参数来验证您是否正确定义了它。