APIディスカバリー

GitLab 15.9で導入されました。API Discovery 機能はベータ版です。

API Discovery はアプリケーションを分析し、公開する Web API を記述した OpenAPI ドキュメントを作成します。このスキーマ・ドキュメントは、DAST APIや API FuzzingによってウェブAPIのセキュリティ・スキャンを実行するために使用することができます。

対応フレームワーク

Java Spring-Boot

API Discoveryはいつ実行されますか？

API Discoveryはパイプラインのスタンドアローンジョブとして実行されます。結果のOpenAPIドキュメントはジョブのアーティファクトとして取り込まれ、後のステージで他のジョブが使用できるようになります。

API Discoveryはtest デフォルトでステージで test実行されます。test この testステージは通常、DAST API や API Fuzzing などの他の API セキュリティ機能で使用されるステージの前に実行されるため、選択されました。

API Discoveryの設定例

以下のプロジェクトはAPI Discoveryのデモです：

Java Spring Boot v2ペットストアの例

Java Spring-Boot

Spring Bootは、スタンドアロンでプロダクショングレードのSpringベースのアプリケーションを作成するための一般的なフレームワークです。

サポートされるアプリケーション

Spring Boot: v2.X (>= 2.1)
Java11、17（LTSバージョン）
実行可能なJAR

API DiscoveryはSpring Bootメジャーバージョン2、マイナーバージョン1以降をサポートしています。バージョン2.0.Xは、API Discoveryに影響する既知のバグがあり、2.1で修正されたため、サポートされていません。

メジャーバージョン3は将来サポートされる予定です。メジャーバージョン1のサポートは予定されていません。

API Discoveryは、JavaランタイムのLTSバージョンでテストされ、公式にサポートされています。他のバージョンでも動作する可能性があり、LTS以外のバージョンからのバグレポーターも歓迎します。

Spring Boot実行可能なJARとしてビルドされたアプリケーションのみがサポートされます。

パイプラインジョブとして設定

API Discoveryを実行する最も簡単な方法は、CIテンプレートに基づくパイプラインジョブを使用することです。この方法で実行する場合、必要な依存関係（適切なJavaランタイムなど）がインストールされたコンテナイメージを提供します。詳細については、「イメージの要件」を参照してください。

イメージ要件を満たすコンテナイメージは、コンテナレジストリにアップロードされます。コンテナレジストリに認証が必要な場合は、このヘルプセクションを参照してください。
build ステージのジョブで、アプリケーションをビルドし、結果のSpring Boot実行可能JARをジョブアーティファクトとして設定します。
API Discoveryテンプレートを.gitlab-ci.yml ファイルに含めます。
```
include:
   - template: Security/API-Discovery.gitlab-ci.yml
```
1つの.gitlab-ci.yml ファイルにつき、include ステートメントを1つだけ含めることができます。他のファイルを含める場合は、1つのinclude ステートメントにまとめてください。
```
include:
   - template: Security/API-Discovery.gitlab-ci.yml
   - template: Security/DAST-API.gitlab-ci.yml
```
.api_discovery_java_spring_bootデフォルト・ステージはtest で、オプションで任意の値に変更できます。
```
api_discovery:
    extends: .api_discovery_java_spring_boot
```

ジョブのimage を設定します。

api_discovery:
    extends: .api_discovery_java_spring_boot
    image: openjdk:11-jre-slim

アプリケーションに必要なJavaクラス・パスを指定します。これには、手順 2 で互換性のあるビルド・アーティファクトと、追加の依存関係が含まれます。この例では、ビルド・アーティファクトはbuild/libs/spring-boot-app-0.0.0.jar で、必要な依存関係がすべて含まれています。変数API_DISCOVERY_JAVA_CLASSPATH を使用して、クラス・パスを指定します。
```
api_discovery:
    extends: .api_discovery_java_spring_boot
    image: openjdk:11-jre-slim
    variables:
        API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
```
オプション。提供されたイメージに API Discovery で必要な依存関係がない場合は、before_script を使用して追加できます。この例では、openjdk:11-jre-slim コンテナに API Discovery で必要なcurl が含まれていません。この依存関係は、Debian パッケージマネージャapt を使用してインストールできます：
```
api_discovery:
    extends: .api_discovery_java_spring_boot
    image: openjdk:11-jre-slim
    variables:
        API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
    before_script:
        - apt-get update && apt-get install -y curl
```

オプション。提供されたイメージがJAVA_HOME 環境変数を自動的に設定しない場合、またはjava をパスに含めない場合、API_DISCOVERY_JAVA_HOME 変数を使用できます。

api_discovery:
    extends: .api_discovery_java_spring_boot
    image: openjdk:11-jre-slim
    variables:
        API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
        API_DISCOVERY_JAVA_HOME: /opt/java

オプション。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: openjdk:8-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 (busybox,sh,bash のような) シェル。

利用可能な CI/CD 変数

CI/CD 変数	説明
`API_DISCOVERY_DISABLED`	テンプレート・ジョブ・ルールを使用している場合は、API Discovery ジョブを無効にします。
`API_DISCOVERY_DISABLED_FOR_DEFAULT_BRANCH`	テンプレートのジョブルールを使用している場合、デフォルトブランチパイプラインの API Discovery ジョブを無効にします。
`API_DISCOVERY_JAVA_CLASSPATH`	対象のSpring Bootアプリケーションを含むJavaクラスパス。(`build/libs/sample-0.0.0.jar`)
`API_DISCOVERY_JAVA_HOME`	提供された場合、`JAVA_HOME` を設定するために使われます。
`API_DISCOVERY_PACKAGES`	GitLab Project Package API Prefix (デフォルトは`$CI_API_V4_URL/projects/42503323/packages`)。
`API_DISCOVERY_PACKAGE_TOKEN`	GitLab パッケージ API を呼び出すための GitLab トークン。`API_DISCOVERY_PACKAGES` が非公開プロジェクトに設定されている場合にのみ必要です。
`API_DISCOVERY_VERSION`	使用する API Discovery バージョン (デフォルトは`1`)。完全なバージョン番号`1.1.0` を指定することで、バージョンを固定することができます。

サポートまたは改善要求

特定の問題についてサポートを受けるには、ヘルプを得るためのチャンネルをご利用ください。

API Discoveryに関するバグや機能提案は、GitLab.comのGitLabイシュー・トラッカーが適切です。API Discoveryに関する新しいイシューを開くときは、~"Category:API Security" ラベルを使用して、適切な担当者が素早くレビューできるようにしてください。レビュアーSLOを参照して、いつレスポンスを受け取るべきかを理解してください。

自分自身の課題を提出する前に、類似のエントリがないかイシュー・トラッカーを検索してください。絵文字によるリアクションやディスカッションへの参加で、あなたのサポートを示しましょう。

期待通りに動作しない動作が発生した場合は、コンテキスト情報を提供することを検討してください：

セルフマネージドインスタンスを使用している場合は GitLab のバージョン。
.gitlab-ci.yml ジョブの定義
完全なジョブコンソール出力。
使用中のフレームワークとバージョン（例：Spring Boot v2.3.2）。
言語ランタイムとバージョン（例：OpenJDK v17.0.1）。

サポート・イシューに添付されたデータをサニタイズします。クレデンシャル、パスワード、トークン、キー、シークレットなどの機密情報を削除します。

APIディスカバリー

対応フレームワーク

API Discoveryはいつ実行されますか？

API Discoveryの設定例

Java Spring-Boot

サポートされるアプリケーション

パイプラインジョブとして設定

画像要件

利用可能な CI/CD 変数

サポートまたは改善要求

Help & feedback

Docs

Product

Feature availability and product trials

Get Help