Automatically preview OpenAPI documents

[lcawl]

🚀 Feature Proposal

Relates to #4367, #4368, which are the issues for automatically linting and deploying the OpenAPI documents.

This proposal is around automatically generating previews.

There is information about this in https://docs.bump.sh/help/continuous-integration/github-actions/ and https://docs.bump.sh/help/continuous-integration/cli/#the-preview-command

Motivation

The Elasticsearch API documents are too big to preview as one-offs locally, but they should work if they're done via a diff and preview command within a GitHub or Buildkite script against the real document within Bump.sh.

Example

One of the other Elastic teams implemented this as a GitHub action like this:

  api-diff:
    if: ${{ github.event_name == 'pull_request' }}
    name: Check API diff on Bump.sh
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
      - name: Create Preview
        uses: bump-sh/github-action@690c81156715f37cb72d006e5cbb81fbd9b45365 # v1
        with:
          doc: xxx
          token: xxx
          file: xxx
          command: preview
        env:
          GITHUB_TOKEN: xxx
      - name: Comment pull request with API diff
        uses: bump-sh/github-action@690c81156715f37cb72d006e5cbb81fbd9b45365 # v1
        with:
          doc: xxx
          token: xxx
          file: xxx
          command: diff
          fail_on_breaking: true
        env:
          GITHUB_TOKEN: xxx

Kibana does not yet have a preview as a part of their process, but their diff and deploy pipelines are visible here: https://github.com/elastic/kibana/blob/main/.buildkite/scripts/steps/openapi_publishing/publish_oas_docs.sh