# OpenAPI Specification からのインポート

:::info
本チュートリアルで扱う機能は、Web アプリケーション診断機能をご契約いただいた組織でのみご利用いただけます。
:::

OpenAPI Specification をもとにエンドポイントをインポートする場合は、以下の手順に従ってください。

## GitHub Actions で自動連携する (推奨)

GitHub Actions を用いてスキーマを Shisho Cloud と自動で連携させる方法について説明します。

### GitHub Actions から Shisho Cloud にログインできるようにする

GitHub Actions から Shisho Cloud にログインできるよう、Shisho Cloud 側の設定をしていきます。まず Shisho Cloud の[ボット作成画面](https://cloud.shisho.dev/*/settings/bots)を開き、「ボット」を作成します。ボットとは Shisho Cloud 組織へのアクセス権限を持つ主体であり、GitHub Actions ジョブはボットとして Shisho Cloud にログインすることになります。

![ボット作成画面](/docs/ja/_md-assets/709014004f-create-bot.png)

ボットを作成したら、ボット名をクリックすると信頼条件の設定画面に遷移します。

![信頼条件の設定画面](/docs/ja/_md-assets/947bafca52-create-trust-condition.png)

信頼条件とは、GitHub Actions ジョブが当該ボットとして Shisho Cloud にログインするために、ジョブが満たすべき条件です。ワークフローが格納されている GitHub リポジトリの Organization およびリポジトリ名を記入すると、当該リポジトリに属する GitHub Actions ジョブが、先ほど作成したボットとして Shisho Cloud にログインできるようになります。記入が完了したら、「保存」ボタンをクリックしてください。

### GitHub Actions Workflow の作成

次のような GitHub Actions Workflow を作成してください。

```yaml
name: "Sync the OpenAPI Specification with Shisho Cloud"

permissions:
  contents: read
  id-token: write # Shisho Cloud にログインするために必要な権限

on:
  push:
    branches:
      - main
    paths:
      # Workflow ファイルのパス
      - .github/workflows/sync-openapi.yaml
      # FIXME: 参照するスキーマファイルのパスに置換してください
      - docs/openapi.yaml

jobs:
  sync:
    name: Sync
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install shishoctl
        run: |
          SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-x86_64-unknown-linux-gnu"
          sudo curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
          sudo chmod +x /usr/local/bin/shishoctl

      - name: Sign in
        uses: flatt-security/shisho-cloud-action@v1
        with:
          # FIXME: 入力すべき bot-id の値は信頼条件の設定画面に記載されています
          bot-id: "BTXXXXXXXXXXXXXXXXXXXXXXXXXX"

      - name: Sync with Shisho Cloud
        run: |
          shishoctl web-application collect-endpoints openapi \
            --org $ORG_ID \
            --app $APP_ID \
            --path $SCHEMA_PATH
        env:
          ORG_ID: ${{ vars.SHISHO_CLOUD_ORG_ID }}
          APP_ID: ${{ vars.SHISHO_CLOUD_APP_ID }}
          # FIXME: 参照するスキーマファイルのパスに置換してください
          SCHEMA_PATH: docs/openapi.yaml
```

コード中の `FIXME` と記載された箇所を適切に書き換えてください。

また次の変数を GitHub リポジトリに登録してください。詳しい設定の方法は [GitHub 公式のドキュメント](https://docs.github.com/ja/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository) を参照してください。

- `SHISHO_CLOUD_ORG_ID` 組織ID
  - Shisho Cloud のダッシュボードの URL に含まれています
  - `https://cloud.shisho.dev/{{ 組織ID }}/dashboard`
- `SHISHO_CLOUD_APP_ID` アプリケーションID
  - アプリケーションページのURLに含まれています
  - `https://cloud.shisho.dev/{{ 組織ID }}/applications/{{ アプリケーションID }}`

## Web コンソールから手動でインポートする

まず、「ジョブ一覧」ページ (`https://cloud.shisho.dev/[orgid]/applications/[appid]/jobs/find`) に移動し、「エンドポイントを登録」ボタンをクリックします。

![「ジョブ一覧」ページ](/docs/ja/_md-assets/d855ac5cb2-crawling-job-list-empty.png)

次に、ボタンを押すと表示されるサイドオーバーにおいて「スキーマファイルをアップロードする」のオプションを選択してください。

![サイドオーバー](/docs/ja/_md-assets/44c0c135b3-crawling-sideover.png)

その後、遷移先の「スキーマアップローダー」ページにおいて「OpenAPI Specification」のオプションを選択してください。
そして、表示される「Click here or drag and drop a OpenAPI Specification file to upload」の箇所をクリックするか、ドラッグアンドドロップにて OpenAPI Specification ファイルをアップロードしてください。

![アップロード画面(初期状態)](/docs/ja/_md-assets/95c7a21c36-upload-openapi-1.png)

ファイルをアップロードすると、フォーム下部にアップロードされた OpenAPI Specification ファイルの内容が表示されます。

![アップロード画面(アップロード後)](/docs/ja/_md-assets/8048073e11-upload-openapi-2.png)

表示された内容で問題なければ、画面下部の「予約」ボタンをクリックしてください。

巡回ジョブを予約してからしばらく待つと、Shisho Cloud はアップロードされた OpenAPI Specification ファイルの内容をもとにエンドポイントを登録します。ジョブの状態が「Completed」になったら、「エンドポイント」タブを開き、エンドポイントが登録されたことを確認してください。