Merge pull request #81 from stacks-network/feat/upgrade-redocly-action

feat: upgrade redocly action

Author: wileyj

openapi/README.md

@@ -6,10 +6,15 @@ Generates an HTML artifact of a provided openapi.yml file using `redoc`, checks
 
 ### Inputs
 
-| Input | Description | Required | Default |
-| ------------------------------- | ----------------------------------------------------- | ------------------------- | ------------------------- |
-| `input` | OpenAPI input file to use | true | null |
-| `output` | OpenAPI artifact filename | false | `./open-api-docs.html` |
+| Input             | Description                                           | Required | Default                |
+| ----------------- | ----------------------------------------------------- | -------- | ---------------------- |
+| `input`           | Input file to use to generate openAPI docs            | `true`   | `(none)`               |
+| `output`          | The path for the generated openAPI output file        | `false`  | `./open-api-docs.html` |
+| `validate`        | Validate OpenAPI spec before generating docs          | `false`  | `true`                 |
+| `redocly-version` | The version of Redocly CLI to use (e.g. 1.34)         | `false`  | `latest`               |
+| `config`          | Path to the Redocly config file for linting           | `false`  | `(none)`               |
+| `node-version`    | Node.js version to use                                | `false`  | `22`                   |
+| `retention-days`  | Number of days to retain the artifact                 | `false`  | `90`                   |
 
 ## Usage
 

openapi/action.yml

@@ -1,9 +1,8 @@
 name: "Generate and upload openAPI docs"
-description: "Generate and upload openAPI docs"
+description: "Generate and upload openAPI docs using Redocly CLI"
 branding:
   icon: "globe"
   color: "gray-dark"
-
 inputs:
   output:
     description: "openAPI output file"
@@ -13,34 +12,119 @@ inputs:
     description: "Input file to use to generate openAPI docs"
     required: true
     default: ""
+  validate:
+    description: "Validate OpenAPI spec before generating docs"
+    required: false
+    default: "true"
+  redocly-version:
+    description: "Version of Redocly CLI to use"
+    required: false
+    default: "latest"
+  config:
+    description: "Path to the Redocly config file for linting"
+    required: false
+  node-version:
+    description: "Node.js version to use"
+    required: false
+    default: "22"
+  retention-days:
+    description: "Number of days to retain the artifact"
+    required: false
+    default: "90"
 
 runs:
   using: "composite"
   steps:
-    ## checkout the code
     - name: Checkout the latest code
       id: git_checkout
       uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-    ## Use redoc to generate HTML of openapi.yml
-    - name: Redoc
+    - name: Detect OpenAPI spec version
+      id: detect_spec
+      shell: bash
+      run: |
+        echo "Detecting if new Redocly-based spec exists..."
+        if [ -f ./docs/rpc/redocly.yaml ]; then
+          echo "use_redocly_cli=true" >> "$GITHUB_OUTPUT"
+          echo "✅ Detected new Redocly spec"
+        else
+          echo "use_redocly_cli=false" >> "$GITHUB_OUTPUT"
+          echo "ℹ️  Falling back to legacy Redoc flow"
+        fi
+
+    - name: Setup Node.js
+      if: steps.detect_spec.outputs.use_redocly_cli == 'true'
+      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      with:
+        node-version: "${{ inputs.node-version }}"
+
+    - name: Install Redocly CLI
+      if: steps.detect_spec.outputs.use_redocly_cli == 'true'
+      id: install_redocly
+      shell: bash
+      run: |
+        npm install -g @redocly/cli@${{ inputs.redocly-version }}
+        echo "✅ Redocly CLI version: $(redocly --version)"
+
+    - name: Validate OpenAPI spec
+      if: inputs.validate == 'true' && steps.detect_spec.outputs.use_redocly_cli == 'true'
+      id: validate_spec
+      shell: bash
+      run: |
+        echo "Validating OpenAPI specification..."
+        CONFIG_ARG=""
+        if [ -n "${{ inputs.config }}" ]; then
+          CONFIG_ARG="--config ${{ inputs.config }}"
+        fi
+        redocly lint ${{ inputs.input }} $CONFIG_ARG
+        echo "✅ OpenAPI specification is valid"
+
+    - name: Generate OpenAPI docs
+      if: steps.detect_spec.outputs.use_redocly_cli == 'true'
+      id: generate_docs
+      shell: bash
+      run: |
+        echo "Generating OpenAPI documentation..."
+        CONFIG_ARG=""
+        if [ -n "${{ inputs.config }}" ]; then
+          CONFIG_ARG="--config ${{ inputs.config }}"
+        fi
+        redocly build-docs ${{ inputs.input }} --output ${{ inputs.output }} $CONFIG_ARG
+        echo "✅ Documentation generated successfully"
+
+    - name: Check result
+      if: steps.detect_spec.outputs.use_redocly_cli == 'true'
+      id: check_result
+      shell: bash
+      run: |
+        echo "Checking if documentation file exists..."
+        if [ ! -f ${{ inputs.output }} ]; then
+          echo "❌ Missing ${{ inputs.output }} from previous step."
+          exit 1
+        fi
+        echo "✅ Generated documentation file is valid"
+        echo "📄 File size: $(du -h ${{ inputs.output }} | cut -f1)"
+
+    - name: Redoc (legacy)
       id: run_redoc
+      if: steps.detect_spec.outputs.use_redocly_cli == 'false'
       uses: seeebiii/redoc-cli-github-action@c9649b33918da5eb290b81cd03a943caea091540 # v10
       with:
         args: "bundle -o ${{ inputs.output }} ${{ inputs.input }}"
 
-    ## Test the resultant html
-    - name: check result
+    - name: Check result (legacy)
       id: check_redoc
+      if: steps.detect_spec.outputs.use_redocly_cli == 'false'
       shell: bash
       run: |
         test -f ${{ inputs.output }} || (echo "Missing ${{ inputs.output }} from previous step." && exit 1)
 
     ## Upload the html file artifact
     - name: Upload bundled html
       id: upload_html_artifact
-      uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
+      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
       with:
         name: open-api-bundle
         path: |
           ${{ inputs.output }}
+        retention-days: ${{ inputs.retention-days }}