legion2 / swagger-ui-action

Generate Swagger UI in a GitHub Actions workflow

Swagger UI Action

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

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. For information about the advanced swagger-config see the Swagger UI Configuration documentation.

Note that, if swagger-config-file or swagger-config-url are used, no files specified in the swagger-config.yaml are copied by this action. 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.

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:

      - 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

For a full example have a look at this workflow file.

Development

The Action runs from GitHub this repo, so the packed dist folder must be added to git.

Release a new version:

$ npm run package
$ git commit -a -m "distribution"
$ npm version major/minor/patch
$ git push
$ git tag -fa v1 -m "Update v1 tag"
$ git push origin v1 --force

Then create a release on GitHub.

versioning documentation

swagger-ui-action's Issues

Any plans to update action to Node.js 20?

Github warns about deprecated Node.js 16. Any plans to update to v20?

"Failed to load API definition." when using `swagger-config-file`

When providing a swagger-config-file (for example swagger-config.yaml), it's copied in the GitHub Pages branch of the repo. However, the specification file path/URL declared in the config file is not. Therefore, when opening the Swagger UI, one gets "Failed to load API definition." with (for example):

Fetch error
undefined openapi.yaml

Workaround

Provide a specification file URL, accessible publicly via Swagger UI.

Proposed solutions

1. Read the config file, find the specification file path, copy it
2. Provide a GitHub Action setting to allow one to provide such a path

Please support wildcard character to match multiply files.

spec-file just support one file, not support multiply swagger files.

"No API definition provided." when using `swagger-config-file`

When providing a swagger-config-file (for example swagger-config.yaml), it's copied as a swagger-config file (without an extension). This file is then used by SwaggerUIBundle in index.html:

// Begin Swagger UI call region
const ui = SwaggerUIBundle({
    configUrl: "swagger-config",
    dom_id: '#swagger-ui'
})
// End Swagger UI call region

(I think) the problem is that when Swagger UI reads the configuration file, it doesn't know what format it's written in (see the documentation about Swagger UI parameters. The resulting Swagger UI is a blank page with "No API definition provided.".

A solution would be to use

const swaggerConfigFileName = basename(config.swaggerConfigFile);
io.cp(
    config.swaggerConfigFile,
    join(config.outputPath, swaggerConfigFileName)
);
return swaggerConfigFileName;

instead of

io.cp(
    config.swaggerConfigFile,
    join(config.outputPath, 'swagger-config')
);
return 'swagger-config';

in swagger-ui-action.ts#L66.

Support SwaggerUI V4?

I'd love to use this action, but with openapi 3.1, and it looks like swaggerUI V4 supports that. Any plan to update this action to use swaggerui v4 instead of v3? or any recommended alternatives?

Vunerable swagger-ui package version

Hey,

Can you please update the package dependencies so that swagger-ui is not within the vulnerable versions ?

Update to Node.js 16?

GitHub left this warning under a recent run of mine:

Node.js 12 actions are deprecated. For more information see: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/. Please update the following actions to use Node.js 16: Legion2/swagger-ui-action, Legion2/swagger-ui-action

Support Authentication

We get the following error:
HttpError: API rate limit exceeded for x.x.x.x. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)

It would be great to support user/token method

Error: No valid Swagger UI releases found

Hi! First of all thank you for maintaining this project.

We'd like to report an issue that we started getting this morning (before it was working well for 2 months).

We have a step in our github workflow whichi is defined as:

      - name: Generate Swagger UI
        uses: Legion2/swagger-ui-action@v1
        with:
          spec-file: ./api.json
          output: ./api_doc

It started failing with the following error message:

##[debug]Evaluating condition for step: 'Generate Swagger UI'
##[debug]Evaluating: success()
##[debug]Evaluating success:
##[debug]=> true
##[debug]Result: true
##[debug]Starting: Generate Swagger UI
##[debug]Loading inputs
##[debug]Loading env
Run Legion2/swagger-ui-action@v1
  with:
    spec-file: ./api.json
    output: ./api_doc
    version: ^3.0.0
  env:
    ENV: ***
    BRANCH: ***
    SSH_AUTH_SOCK: /ssh-agent.sock
/usr/bin/docker exec  e060751954ce1cb27d97366545a427f7649a79229efddcad04bede8f9ff2b5d1 sh -c "cat /etc/*release | grep ^ID"
##[debug]ID=ubuntu
##[debug]ID_LIKE=debian
##[debug]Running JavaScript Action with default external tool: node12
Error: No valid Swagger UI releases found
Error: Error: No valid Swagger UI releases found
##[debug]Node Action run completed with exit code 1
##[debug]Finishing: Generate Swagger UI

From what I see, the error is originates from this place: https://github.com/Legion2/swagger-ui-action/blob/main/src/swagger-ui-action.ts#L201

It looks like it cannot find the matching release (3.0.0), but it's there: https://github.com/swagger-api/swagger-ui/releases/tag/v3.0.0

Thank you in advance.

Wrong input name

Introduction

Currently the input name for github token is: GITHUB_TOKEN but this name are depreciated.