APIディスカバリ

API Discoveryはアプリケーションを分析し、公開するWeb APIを記述したOpenAPIドキュメントを生成します。このスキーマドキュメントは、Web APIのセキュリティスキャンを実行するために、APIセキュリティテストアナライザーまたはAPIファジングで使用できます。

サポートされているフレームワーク

• Java Spring-Boot

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

API Discoveryは、パイプライン内でスタンドアロンのジョブとして実行されます。結果のOpenAPIドキュメントはジョブアーティファクトとしてキャプチャされるため、以降のパイプラインステージの他のジョブで使用できます。

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

API Discoveryの設定例

以下のプロジェクトがAPI Discoveryを示しています:

• Java Spring Boot v2 Pet Storeの例

Java Spring-Boot

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

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

• Spring Boot: v2.X (>= 2.1)
• Java: 11、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ランタイムなど）を提供します。詳細については、Image Requirementsを参照してください。

1. image requirementsを満たすコンテナイメージがレジストリにアップロードされます。コンテナレジストリで認証が必要な場合は、このヘルプセクションを参照してください。

2. buildパイプラインステージのジョブで、アプリケーションをビルドし、結果のSpring Boot実行可能JARをジョブアーティファクトとして設定します。

3. API Discoveryテンプレートを.gitlab-ci.ymlファイルに含めます。

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

   includeステートメントは.gitlab-ci.ymlファイルごとに1つのみ許可されます。他のファイルを含める場合は、単一の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 Self-Managedインスタンスを使用している場合のGitLabバージョン。
• .gitlab-ci.ymlジョブ定義。
• 完全なジョブコンソール出力。
• 使用中のフレームワークとそのバージョン（例：「Spring Boot v2.3.2」）。
• 言語ランタイムとそのバージョン（例：「Eclipse Temurin v17.0.1」）。