API 发现

API Discovery 分析您的应用程序，生成一个描述其暴露的 Web API 的 OpenAPI 文档。该架构文档随后可被 API 安全测试分析器 或 API 模糊测试 用于执行 Web API 的安全扫描。

支持的框架

• Java Spring-Boot

API Discovery 何时运行？

API Discovery 作为独立作业在您的流水线中运行。生成的 OpenAPI 文档会被捕获为作业产物，以便后续阶段的作业可以使用。

默认情况下，API Discovery 在 test 阶段运行。选择 test 阶段是因为它通常在其他安全功能（如 API 安全测试和 API 模糊测试）使用的阶段之前执行。

API Discovery 配置示例

以下项目展示了 API Discovery：

• 示例 Java Spring Boot v2 宠物商店

Java Spring-Boot

Spring Boot 是一个流行的框架，用于创建独立的、生产级的基于 Spring 的应用程序。

支持的应用程序

• Spring Boot：v2.X (>= 2.1)
• Java：11, 17 (LTS 版本)
• 可执行 JAR

API Discovery 支持 Spring Boot 主版本 2，次版本 1 及更高版本。由于已知影响 API Discovery 的错误已在 2.1 中修复，因此不支持 2.0.X 版本。

计划在未来支持主版本 3。不支持主版本 1。

API Discovery 经过测试并正式支持 Java 运行时的 LTS 版本。其他版本也可能工作，欢迎来自非 LTS 版本的错误报告。

仅支持构建为 Spring Boot 可执行 JAR 的应用程序。

配置为流水线作业

运行 API Discovery 最简单的方法是基于我们的 CI 模板创建流水线作业。 以这种方式运行时，您需要提供一个已安装所需依赖项的容器镜像（如适当的 Java 运行时）。有关更多信息，请参阅 镜像要求。

1. 将满足 镜像要求 的容器镜像上传到容器注册表。如果容器注册表需要身份验证，请参阅此帮助部分。

2. 在 build 阶段的作业中，构建您的应用程序并将生成的 Spring Boot 可执行 JAR 配置为作业产物。

3. 在您的 .gitlab-ci.yml 文件中包含 API Discovery 模板。

   include:
      - template: Security/API-Discovery.gitlab-ci.yml

   每个 .gitlab-ci.yml 文件只允许一个 include 语句。如果您包含其他文件，请将它们合并到一个 include 语句中。

   include:
      - template: Security/API-Discovery.gitlab-ci.yml
      - template: Security/DAST-API.gitlab-ci.yml

4. 创建一个扩展自 .api_discovery_java_spring_boot 的新作业。默认阶段是 test，可以可选地更改为任何值。

   api_discovery:
       extends: .api_discovery_java_spring_boot

5. 为作业配置 image。

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-jre-alpine

6. 提供应用程序所需的 Java 类路径。这包括您在步骤 2 中兼容的构建产物，以及任何额外的依赖项。在此示例中，构建产物是 build/libs/spring-boot-app-0.0.0.jar，并包含所有需要的依赖项。变量 API_DISCOVERY_JAVA_CLASSPATH 用于提供类路径。

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-jre-alpine
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar

7. 可选。如果提供的镜像缺少 API Discovery 所需的依赖项，可以使用 before_script 添加。在此示例中，eclipse-temurin:17-jre-alpine 容器不包含 API Discovery 所需的 curl。可以使用 Debian 包管理器 apt 安装该依赖项：

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-jre-alpine
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
       before_script:
           - apk add --no-cache curl

8. 可选。如果提供的镜像没有自动设置 JAVA_HOME 环境变量，或在路径中包含 java，可以使用 API_DISCOVERY_JAVA_HOME 变量。

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-jre-alpine
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
           API_DISCOVERY_JAVA_HOME: /opt/java

9. 可选。如果 API_DISCOVERY_PACKAGES 处的包注册表不是公开的，请使用 API_DISCOVERY_PACKAGE_TOKEN 变量提供一个具有 GitLab API 和注册表读取权限的令牌。如果您使用的是 gitlab.com 并且没有自定义 API_DISCOVERY_PACKAGES 变量，则不需要此操作。以下示例使用一个名为 GITLAB_READ_TOKEN 的自定义 CI/CD 变量来存储令牌。

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-jre-alpine
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
           API_DISCOVERY_PACKAGE_TOKEN: $GITLAB_READ_TOKEN

API Discovery 作业成功运行后，OpenAPI 文档将作为名为 gl-api-discovery-openapi.json 的作业产物提供。

镜像要求

• Linux 容器镜像。
• Java 版本 11 或 17 是官方支持的，但其他版本也可能兼容。
• curl 命令。
• /bin/sh 处的 shell（如 busybox、sh 或 bash）。

可用的 CI/CD 变量

获取支持或请求改进

获取特定问题的支持，请使用获取帮助渠道。

GitLab.com 上的 GitLab 问题跟踪器是报告 API Discovery 错误和功能建议的正确位置。 在打开有关 API Discovery 的新问题时，请使用 ~"Category:API Security" 标签，以确保它能够被相关人员快速审查。

在提交您自己的问题之前，搜索问题跟踪器中是否有类似的条目，很可能其他人已经遇到过相同的问题或功能建议。使用表情符号反应表示支持或加入讨论。

当遇到不符合预期的行为时，请考虑提供上下文信息：

• 如果使用 GitLab 自托管实例，请提供 GitLab 版本。
• .gitlab-ci.yml 作业定义。
• 完整的作业控制台输出。
• 使用的框架及其版本（例如 “Spring Boot v2.3.2”）。
• 语言运行时及其版本（例如 “Eclipse Temurin v17.0.1”）。