Coursera 笔记

Module 02 · Web API Essentials: REST API and GraphQL

Documenting and Testing REST APIs with Swagger使用 Swagger 文档化和测试 REST API

Coursera ↗

API 文档与 Swagger

API 指定了一个接口，连接不同的系统，并为其提供一致的通信。

  • API 文档: 类似于一个参考手册，包含有关有效使用和集成系统的说明。
  • Swagger 的作用: Swagger 通过运行 OpenAPI 规范来确保您符合指南，从而节省编写 API 文档的时间。
  • 机器可读: Swagger 允许您描述 API 的结构，以便机器可以读取它们。
  • 自动生成 UI: 利用 API 的结构，Swagger 会自动构建引人入胜的 UI 和交互式 API 文档。
    • 这种结构定义在一个遵循 OpenAPI 规范的 JSON 或 YAML 文件中。

OpenAPI 规范（OAS）

最初，API 并非为自助式消费而设计。OpenAPI 规范定义了一个标准、语言无关的 RESTful API 接口。

OAS 的核心特性

  • 语言无关: 规范是语言无关的，并且是人机可读的。
  • 发现能力: 允许个人和计算机发现和理解服务的能力，而无需访问源代码、额外文档或检查网络流量。

OAS 定义的内容

OAS 定义了您的 API 的所有关键方面：

  • 操作: 您的 API 支持的所有操作。
  • 参数与返回: 所需的参数和预期的返回。
  • 认证: 所需的 API 认证。
  • 附加信息:
    • 服务条款（terms of service）。
    • 联系信息（contact information）。
    • 暴露 API 的许可信息（license information）。

将 Swagger UI 集成到 Flask 应用

Flask 使 Python 函数可以暴露为 API。Flask Swagger UI 通过允许您描述和可视化 REST API 来增强其功能。

1. 安装与导入

  • 安装: 使用 pip install Flask-swagger-ui 命令将 Swagger UI 添加到您的 Flask 应用程序中。
  • 导入: 需要导入 swagger_ui_blueprint 来帮助您使用 Flask 创建 Swagger UI。

2. 配置与注册

  • 基本配置: 定义基本配置，包括：
    • Swagger 可用路径: 在本例中为 products/docs。
    • Swagger 文件服务位置: 第二个参数显示 Swagger 文件（swagger.json）的服务位置。
    • Swagger 名称。
  • 注册蓝图: 需要使用 app.register_blueprint() 向 Flask 注册此蓝图。

3. 暴露 Swagger JSON 文件

  • swagger.json 文件包含了 API 的定义和特性。
  • 您需要暴露一个路由，用于提供这个静态的 swagger.json 文件。

4. 定义 Swagger JSON 内容

  • Swagger JSON 文件需要包含一些基本配置。
  • 示例配置: 创建 Products 微服务 API 的 Swagger 定义，并提供：
    • info 部分（例如联系信息、服务条款等）。
    • 模型（Model）和路径（Path）用于获取产品列表。
    • 定义 Product 对象的属性。

使用 Swagger UI 进行测试

一旦有了 API 定义和 Swagger UI，您就可以利用其核心优势：

  • API 测试: 您可以使用 UI 直接测试您的 API，这是使用 Swagger 的关键优势。
  • 详细信息: 它允许消费者获取有关您的 API 的更多详细信息、支持的功能、请求和响应。
  • 可视化: UI 会显示产品信息部分的内容以及唯一可用的方法（用于检索所有产品的 GET 请求）。
  • 执行: 您可以直接执行该端点并查看结果（在本例中为产品列表）。

总结

  • Swagger 帮助您文档化您的 API。
  • OpenAPI 规范是表示您的 API 的标准方式。
  • Swagger 提供了一个测试您的 API 的机制。