From d5e7aef591c68bafa933b351472d975f3f6fc273 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 21 Dec 2025 06:31:22 +0000 Subject: [PATCH 1/3] Initial plan From f183bf9d4fdcb7803661325aeba3d7e40ca8d840 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 21 Dec 2025 06:34:55 +0000 Subject: [PATCH 2/3] Improve documentation of the 'version' input in README Co-authored-by: Legion2 <12752323+Legion2@users.noreply.github.com> --- README.md | 48 +++++++++++++++++++++++++++++++----------------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 19a6364..5a48e8f 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,17 @@ # Swagger UI Action [![build-test](https://github.com/Legion2/swagger-ui-action/workflows/build-test/badge.svg)](https://github.com/Legion2/swagger-ui-action/actions?query=workflow%3Abuild-test+branch%3Amain) + Generate Swagger UI static html files and configuration to be deployed to GitHub Pages. > This action only works on linux runners. + ## How to Use + This Action supports four different configuration modes: - * `spec-file`: File path to local OpenAPI or Swagger specification document - * `spec-url`: URL of an OpenAPI or Swagger specification document - * `swagger-config-file`: File path to local swagger configuration file - * `swagger-config-url`: URL of a swagger configuration file + +- `spec-file`: File path to local OpenAPI or Swagger specification document +- `spec-url`: URL of an OpenAPI or Swagger specification document +- `swagger-config-file`: File path to local swagger configuration file +- `swagger-config-url`: URL of a swagger configuration file Use `spec-file` or `spec-url` when you have an OpenAPI or Swagger specification document and want a basic Swagger UI generated for it. If you want to customize the created Swagger UI, you should use the `swagger-config-file` or the `swagger-config-url` configuration modes. @@ -17,36 +21,46 @@ Note that, if `swagger-config-file` or `swagger-config-url` are used, no files s In this case, it is your responsibility to copy required files such as the OpenAPI document where you need them (output directory). The output directory of the generated Swagger UI must be set with the `output` argument of the Action. -Optionally the Swagger UI version can be set with the `version` input, it accepts semver ranges. + +### Version Input + +The `version` input controls which version of Swagger UI is used to generate the documentation. +It accepts [semver ranges](https://semver.org/), allowing you to specify exact versions (e.g., `5.0.0`), major versions (e.g., `5.x`), or ranges (e.g., `^3.0.0`). +If not specified, it defaults to `^3.0.0`. +Using version ranges ensures you automatically get the latest compatible version without manually updating your workflow. The `GITHUB_TOKEN` secret must be provided to the action. It is used to query the Github api and download the release files of Swagger UI. ### Example + This Action only generates the Swagger UI. For example, to deploy it to GitHub Pages another Action is required. Example steps from a workflow to generate and deploy Swagger UI to GitHub Pages: + ```yaml - - name: Generate Swagger UI - uses: Legion2/swagger-ui-action@v1 - with: - output: swagger-ui - spec-file: openapi.json - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: swagger-ui +- name: Generate Swagger UI + uses: Legion2/swagger-ui-action@v1 + with: + output: swagger-ui + spec-file: openapi.json + version: 5.x + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +- name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: swagger-ui ``` For a full example have a look at [this workflow file](https://github.com/Legion2/open-cue-service/blob/master/.github/workflows/pages.yml). ## Development -The Action runs from GitHub this repo, so the packed dist folder must be added to git. +The Action runs from GitHub this repo, so the packed dist folder must be added to git. Release a new version: + ```bash $ npm run package $ git commit -a -m "distribution" From da555ba52c5d2eb2d4a4301ddf2a9a65e8f835f4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 21 Dec 2025 06:36:18 +0000 Subject: [PATCH 3/3] Update semver link to point to npm range documentation Co-authored-by: Legion2 <12752323+Legion2@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5a48e8f..40fd559 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ The output directory of the generated Swagger UI must be set with the `output` a ### Version Input The `version` input controls which version of Swagger UI is used to generate the documentation. -It accepts [semver ranges](https://semver.org/), allowing you to specify exact versions (e.g., `5.0.0`), major versions (e.g., `5.x`), or ranges (e.g., `^3.0.0`). +It accepts [semver ranges](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges), allowing you to specify exact versions (e.g., `5.0.0`), major versions (e.g., `5.x`), or ranges (e.g., `^3.0.0`). If not specified, it defaults to `^3.0.0`. Using version ranges ensures you automatically get the latest compatible version without manually updating your workflow.