action.yaml

name: Build and upload API docs
description: Build HTML API documentation from an OpenAPI spec and upload it to S3
inputs:
  spec:
    description: The path to the API spec
    required: true
  bucket:
    description: The bucket to upload to
    required: true
  accessKeyId:
    description: The AWS access key ID
    required: true
  secretKey:
    description: The AWS secret access key
    required: true
  urlPrefix:
    description: The URL prefix to publicly access bucket contents
    required: true
outputs:
  url:
    description: The URL of the uploaded API spec
    value: ${{steps.meta.outputs.url}}
  commitUrl:
    description: The URL of the uploaded API spec (by commit)
    value: ${{steps.meta.outputs.commitUrl}}
runs:
  using: composite
  steps:
    - name: Generate metadata
      id: meta
      shell: bash
      run: |
        prefix="${{github.event.repository.name}}"
        sha="${{github.event.pull_request.head.sha || github.sha}}"
        commitPrefix="$prefix/commits/$sha"
        case "${{github.event_name}}" in
          pull_request)
            prefix="$prefix/pull-requests/${{github.event.pull_request.number}}"
            ;;
          release)
            prefix="$prefix/release/${{github.event.release.name}}"
            ;;
          push)
            prefix="$prefix/branch/${GITHUB_REF#refs/heads/}"
            ;;
        esac
        echo "prefix=$prefix" >> $GITHUB_OUTPUT
        echo "sha=$sha" >> $GITHUB_OUTPUT
        echo "url=${{inputs.urlPrefix}}/$prefix/index.html" >> $GITHUB_OUTPUT
        echo "commitPrefix=$commitPrefix" >> $GITHUB_OUTPUT
        echo "commitUrl=${{inputs.urlPrefix}}/$commitPrefix/index.html" >> $GITHUB_OUTPUT
    - name: Build docs
      id: build
      shell: bash
      run: |
        yaml2json() { python3 -c 'import sys,yaml,json;print(json.dumps(yaml.safe_load(sys.stdin.read())))'; }
        json2yaml() { python3 -c 'import sys,yaml,json;print(yaml.dump(json.loads(sys.stdin.read())))'; }
        in="$(mktemp)"
        out="$(mktemp)"
        if [ "${{github.event_name}}" = "release" ]; then
          yaml2json < "${{inputs.spec}}" | jq '.info.version = "${{github.event.release.name}}"' | json2yaml > "$in"
        else
          yaml2json < "${{inputs.spec}}" | jq '.info.version = "${{steps.meta.outputs.sha}}"' | json2yaml > "$in"
        fi
        docker pull -q redocly/cli
        docker run --rm -v "$in:/spec.yaml" -v "$out:/out.html" redocly/cli build-docs /spec.yaml -o /out.html
        echo "out=$out" >> $GITHUB_OUTPUT
    - name: Upload docs
      shell: bash
      run: |
        sudo wget -q 'https://dl.min.io/client/mc/release/linux-amd64/mc' -O/usr/local/bin/mc
        sudo chmod +x /usr/local/bin/mc
        mc alias set --api s3v4 --path off s3 https://s3.amazonaws.com "${{inputs.accessKeyId}}" "${{inputs.secretKey}}"
        mc cp "${{steps.build.outputs.out}}" "s3/${{inputs.bucket}}/${{steps.meta.outputs.prefix}}/index.html"
        if [ "${{github.event_name}}" = "release" ]; then
          curl -L \
            -X POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer ${{github.token}}" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            -H "Content-Type: text/html" \
            "https://uploads.github.com/repos/${{github.repository}}/releases/${{github.event.release.id}}/assets?name=${{github.event.repository.name}}-${{github.event.release.tag_name}}-api-docs.html" \
            --data-binary "@${{steps.build.outputs.out}}"
        else
          mc cp "${{steps.build.outputs.out}}" "s3/${{inputs.bucket}}/${{steps.meta.outputs.commitPrefix}}/index.html"
        fi
    - name: Submit commit status
      shell: bash
      run: |
        if [ "${{github.event_name}}" = "release" ]; then
          url="${{steps.meta.outputs.url}}"
        else
          url="${{steps.meta.outputs.commitUrl}}"
        fi
        curl -L \
          -X POST \
          -H "Accept: application/vnd.github+json" \
          -H "Authorization: Bearer ${{github.token}}" \
          -H "X-GitHub-Api-Version: 2022-11-28" \
          "https://api.github.com/repos/${{github.repository}}/statuses/${{steps.meta.outputs.sha}}" \
          -d @- <<EOF
          {
            "state": "success",
            "target_url": "$url",
            "description": "View API documentation",
            "context": "API Documentation"
          }
        EOF