From 891a4dc13197742fe053fe6b5a5cb3711381d81b Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 8 Jul 2025 17:48:20 +0200 Subject: [PATCH 01/10] drop outdated seeebiii/redoc-cli-github-action for redocly/cli --- openapi/action.yml | 72 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 59 insertions(+), 13 deletions(-) diff --git a/openapi/action.yml b/openapi/action.yml index bea1960..833a1ea 100644 --- a/openapi/action.yml +++ b/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,81 @@ 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 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 - id: run_redoc - uses: seeebiii/redoc-cli-github-action@c9649b33918da5eb290b81cd03a943caea091540 # v10 + - name: Setup Node.js + uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: - args: "bundle -o ${{ inputs.output }} ${{ inputs.input }}" + node-version: "20" + cache: "npm" + + - name: Install Redocly CLI + id: install_redocly + shell: bash + run: | + if [ "${{ inputs.redocly-version }}" = "latest" ]; then + npm install -g @redocly/cli + else + npm install -g @redocly/cli@${{ inputs.redocly-version }} + fi + echo "Redocly CLI version: $(redocly --version)" + + - name: Validate OpenAPI spec + id: validate_spec + if: inputs.validate == "true" + 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 + 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" - ## Test the resultant html - - name: check result - id: check_redoc + - name: Check result + id: check_result shell: bash run: | - test -f ${{ inputs.output }} || (echo "Missing ${{ inputs.output }} from previous step." && exit 1) + test -f ${{ inputs.output }} || (echo "❌ Missing ${{ inputs.output }} from previous step." && exit 1) + echo "✅ Generated documentation file is valid" + echo "📄 File size: $(du -h ${{ inputs.output }} | cut -f1)" ## 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: 30 From 905657d803b20fdd91b3f0ddc65e4e43b1d61647 Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 8 Jul 2025 17:54:19 +0200 Subject: [PATCH 02/10] update openapi action readme --- openapi/README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/openapi/README.md b/openapi/README.md index 5f736ad..afefb37 100644 --- a/openapi/README.md +++ b/openapi/README.md @@ -6,10 +6,13 @@ 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)` | ## Usage From ffed1a6da0961baa86c63e3a4cae08a56ad50885 Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 8 Jul 2025 18:02:20 +0200 Subject: [PATCH 03/10] use single quotes --- openapi/action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/action.yml b/openapi/action.yml index 833a1ea..20045fc 100644 --- a/openapi/action.yml +++ b/openapi/action.yml @@ -50,7 +50,7 @@ runs: - name: Validate OpenAPI spec id: validate_spec - if: inputs.validate == "true" + if: inputs.validate == 'true' shell: bash run: | echo "Validating OpenAPI specification..." From c62aa35b841150b864b5874c4551e10143f6a70c Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 8 Jul 2025 18:19:03 +0200 Subject: [PATCH 04/10] remove npm cache --- openapi/action.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/openapi/action.yml b/openapi/action.yml index 20045fc..41647f1 100644 --- a/openapi/action.yml +++ b/openapi/action.yml @@ -35,7 +35,6 @@ runs: uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: "20" - cache: "npm" - name: Install Redocly CLI id: install_redocly From 6f6ecee9f6011f0b96c4a05dd5703a33674dd320 Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 8 Jul 2025 18:52:48 +0200 Subject: [PATCH 05/10] split file check in multiple lines --- openapi/action.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/openapi/action.yml b/openapi/action.yml index 41647f1..840c6d3 100644 --- a/openapi/action.yml +++ b/openapi/action.yml @@ -76,7 +76,11 @@ runs: id: check_result shell: bash run: | - test -f ${{ inputs.output }} || (echo "❌ Missing ${{ inputs.output }} from previous step." && exit 1) + 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)" From b18550eecc32b7b26ceb720e0acb3dc636c71028 Mon Sep 17 00:00:00 2001 From: Francesco <2530388+Jiloc@users.noreply.github.com> Date: Wed, 9 Jul 2025 08:44:12 +0200 Subject: [PATCH 06/10] Update openapi/action.yml Co-authored-by: wileyj <2847772+wileyj@users.noreply.github.com> --- openapi/action.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/openapi/action.yml b/openapi/action.yml index 840c6d3..0727f8b 100644 --- a/openapi/action.yml +++ b/openapi/action.yml @@ -40,10 +40,7 @@ runs: id: install_redocly shell: bash run: | - if [ "${{ inputs.redocly-version }}" = "latest" ]; then - npm install -g @redocly/cli - else - npm install -g @redocly/cli@${{ inputs.redocly-version }} + npm install -g @redocly/cli@${{ inputs.redocly-version }} fi echo "Redocly CLI version: $(redocly --version)" From cc50a2d1f11d2dee5e2c17b4aca8ea89f42ca77b Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Wed, 9 Jul 2025 10:45:57 +0200 Subject: [PATCH 07/10] add node-version and retention-days params --- openapi/action.yml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/openapi/action.yml b/openapi/action.yml index 840c6d3..3da10d4 100644 --- a/openapi/action.yml +++ b/openapi/action.yml @@ -23,6 +23,14 @@ inputs: 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" @@ -34,7 +42,7 @@ runs: - name: Setup Node.js uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: - node-version: "20" + node-version: "${{ inputs.node-version }}" - name: Install Redocly CLI id: install_redocly @@ -92,4 +100,4 @@ runs: name: open-api-bundle path: | ${{ inputs.output }} - retention-days: 30 + retention-days: ${{ inputs.retention-days }} From dd34fc5c73d7429372fa79562f7a35aa5637a0b7 Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Wed, 9 Jul 2025 12:14:00 +0200 Subject: [PATCH 08/10] remove fi leftover --- openapi/action.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/openapi/action.yml b/openapi/action.yml index 1491980..e9c60ef 100644 --- a/openapi/action.yml +++ b/openapi/action.yml @@ -49,8 +49,7 @@ runs: shell: bash run: | npm install -g @redocly/cli@${{ inputs.redocly-version }} - fi - echo "Redocly CLI version: $(redocly --version)" + echo "✅ Redocly CLI version: $(redocly --version)" - name: Validate OpenAPI spec id: validate_spec From 3e286c6767b3628ea401086526f88bdde16f2d8b Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Wed, 9 Jul 2025 12:14:55 +0200 Subject: [PATCH 09/10] update readme --- openapi/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/openapi/README.md b/openapi/README.md index afefb37..2900915 100644 --- a/openapi/README.md +++ b/openapi/README.md @@ -13,6 +13,8 @@ Generates an HTML artifact of a provided openapi.yml file using `redoc`, checks | `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 From 42c4d4057b31026661adc2752efaf38af8aa59ec Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Mon, 14 Jul 2025 10:49:03 +0200 Subject: [PATCH 10/10] add fallback to legacy redoc-cli --- openapi/action.yml | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/openapi/action.yml b/openapi/action.yml index e9c60ef..66e83d9 100644 --- a/openapi/action.yml +++ b/openapi/action.yml @@ -39,12 +39,27 @@ runs: id: git_checkout uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - 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: | @@ -52,8 +67,8 @@ runs: 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 - if: inputs.validate == 'true' shell: bash run: | echo "Validating OpenAPI specification..." @@ -65,6 +80,7 @@ runs: echo "✅ OpenAPI specification is valid" - name: Generate OpenAPI docs + if: steps.detect_spec.outputs.use_redocly_cli == 'true' id: generate_docs shell: bash run: | @@ -77,6 +93,7 @@ runs: echo "✅ Documentation generated successfully" - name: Check result + if: steps.detect_spec.outputs.use_redocly_cli == 'true' id: check_result shell: bash run: | @@ -88,6 +105,20 @@ runs: 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 }}" + + - 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