适用于AWS API Gateway的无服务器Swagger UI - tecRacer

在AWS（API自动生成交互式且始终最新的文档。

简介

API网关功能强大，但在许多项目中，文档的缺乏或过时是一个常见问题。

高质量的文档对于入职培训、流程控制和知识共享至关重要，但维护文档的更新需要耗费大量时间，尤其是在API频繁迭代的情况下。为了解决这一问题，我们可以使用Swagger UI，它是一组开源工具，能够根据OpenAPI规范自动生成交互式API文档。开发者和消费者可以通过这些文档测试、验证或直接与API交互。

在本文中，我们将使用Terraform为API网关设置一个无服务器的Swagger UI。

架构概述

在开始实现Terraform代码之前，我们先了解一下示例基础设施的架构。如下图所示，我们将使用四个资源创建一个简单的API网关。

在这个示例中，每个资源都将通过AWS Lambda函数与API网关代理集成来处理用户请求。本文的重点是实现和设置生成Swagger UI的Lambda函数，我们将其称为“Swagger UI处理程序”。

设置项目结构

首先，我们需要创建项目的文件结构，以便实现所需功能。以下是需要创建的文件和文件夹：

• main.tf 和 outputs.tf：包含Terraform代码。
• api-gateway-definition.yaml：包含OpenAPI规范。
• orders.js：定义/orders资源的请求处理逻辑。
• app.js：定义“Swagger UI处理程序”的逻辑。
• Swagger-UI/layers/commonLibs/nodejs/：包含Node.js依赖项的package.json。

创建API网关

在完成文件结构的创建后，我们首先使用创建一个API网关。以下是main.tf和api-gateway-definition.[yaml](https://www.explinks.com/wiki/ymal/)的代码片段：

# main.tf 示例代码
# 省略具体代码内容以保持简洁

运行以下命令初始化并部署基础设施：

terraform init
terraform apply

在AWS控制台中检查，您将看到一个REST API已被成功创建。

创建/订单请求处理程序

接下来，我们为/orders资源创建一个Lambda函数，并在Terraform中定义其执行角色。以下是相关代码片段：

# main.tf 示例代码
# 省略具体代码内容以保持简洁

运行以下命令部署Lambda函数：

terraform init
terraform apply

部署完成后，您将在AWS控制台中看到一个新的Lambda函数。

添加集成请求

为了将API与Lambda函数连接，我们需要在Terraform中调整API网关资源，使用模板占位符动态替换Lambda函数的ARN。以下是调整后的代码片段：

# main.tf 示例代码
# 省略具体代码内容以保持简洁

再次运行terraform apply，您将看到集成请求已成功添加到API网关的/orders资源中。

创建Swagger UI处理程序函数

“Swagger UI处理程序”的逻辑稍微复杂一些。以下是需要用到的主要包：

• aws-sdk：用于与API网关通信。
• express：用于创建Web服务器。
• serverless-http：用于将Web服务器封装为无服务器函数。
• swagger-ui-express：用于提供Swagger UI文档。

在详细讨论逻辑后，我们通过Terraform快速部署该Lambda函数。以下是相关步骤：

1. 定义app.js逻辑。
2. 使用package.json定义依赖项，并运行npm install下载所需包。
3. 压缩依赖项目录并创建Lambda层。
4. 在Terraform中定义Lambda函数及其IAM角色。

运行以下命令部署处理程序：

terraform apply

部署完成后，您将在AWS控制台中看到新的Lambda函数和Lambda层。

向API网关添加/api-docs

为了通过/api-docs访问Swagger UI文档，我们需要在api-gateway-definition.yaml中添加以下代码片段：

# paths 部分的代码片段
# 省略具体代码内容以保持简洁

运行terraform apply，您将在API网关控制台中看到新的资源和集成请求。

发布API

最后，我们需要将API部署到一个阶段中，使其公开可用。

控制台部署

1. 在API网关控制台中，点击“操作”并选择“部署API”。
2. 创建一个新阶段并命名，点击“部署”。

Terraform部署

通过以下代码片段在Terraform中创建阶段：

# Terraform 部署阶段的代码片段
# 省略具体代码内容以保持简洁

运行terraform apply完成部署。

结果

部署完成后，您可以通过Terraform输出的URL访问Swagger UI文档。以下是最终效果：

总结

通过Amazon API网关结合Swagger UI，您可以轻松创建交互式API文档，并确保文档始终保持最新。使用无服务器方法不仅减少了维护成本，还能让开发者专注于核心开发工作。

希望本文对您有所帮助！如果您有任何问题或反馈，欢迎留言讨论。

原文链接: https://www.tecracer.com/blog/2023/03/serverless-swagger-ui-for-aws-api-gateway.html