char0n / swagger-editor-validate

This GitHub Actions validates OpenAPI (OAS) definition file using Swagger Editor.

Swagger Editor Validate Github Action

This GitHub Action validates OpenAPI (OAS) definition file using Swagger Editor.

It's handy for use-cases when OAS definition is maintained manually and is checked within the git. If modifications are made to the OAS definition you want to make sure that there are no errors introduced by modifications. Errors that would appear in Swagger Editor when the OAS definition would be pasted inside it.

If you're interested about technical design and evolution of this GitHub Action please read our release article.

Inputs

swagger-editor-url

Optional Defines URL of swagger-editor where definition file is going to be validated. Default https://editor.swagger.io/.

definition-file

Required Defines path of OAS definition file that exists as a physical file in your repository.

ignore-error

Optional Defines path to JavaScript file containing predicate for determining if the error should be ignored or not.

Example usage

There are two major use-cases of how to use this GitHub Action.

Public use-case

If you have access to the internet and don't mind that this action sends your OAS definition to https://editor.swagger.io/ for validation.

on: [push]

jobs:
  test_swagger_editor_validator_remote:
    runs-on: ubuntu-latest
    name: Swagger Editor Validator Remote

    steps:
      - uses: actions/checkout@v2
      - name: Validate OpenAPI definition
        uses: char0n/swagger-editor-validate@v1
        with:
          definition-file: examples/openapi-2-0.yaml

Private use-case

If you want to maintain complete privacy and your OAS definition may contain sensitive information use the following workflow. The workflow uses swagger-editor docker image that runs as service of the workflow.

on: [push]

jobs:
  test_swagger_editor_validator_service:
    runs-on: ubuntu-latest
    name: Swagger Editor Validator Service

    # Service containers to run with `runner-job`
    services:
      # Label used to access the service container
      swagger-editor:
        # Docker Hub image
        image: swaggerapi/swagger-editor
        ports:
          # Maps port 8080 on service container to the host 80
          - 80:8080

    steps:
      - uses: actions/checkout@v2
      - name: Validate OpenAPI definition
        uses: char0n/swagger-editor-validate@v1
        with:
          swagger-editor-url: http://localhost/
          definition-file: examples/openapi-2-0.yaml

swagger-editor-validate's Issues

Support `next` swagger editor (for OpenAPI 3.1)

Is your feature request related to a problem? Please describe.

Error: Error while validating in Swagger Editor
Error: TimeoutError: waiting for selector `.info .main .title` failed: timeout 30000ms exceeded
Error: Process completed with exit code 1.

Describe the solution you'd like

Support different way of error reporting in the next swagger editor:
https://editor-next.swagger.io/

Describe alternatives you've considered

I haven't :)

Additional context

I'd like to validate the schemas against OpenAPI version 3.1 which is currently supported by the next generation of swagger editor. Since this action allows to specify the editor URL, I believe it would be a nice feature to support the next generation as well.
It should be not too difficult, I presume. Just lookup for another set of selectors.

What do you think?

Wrong $ref validation for remote references in OAS3

Describe the bug
The action wrongfully takes as an error having $ref that are remote references

To Reproduce
Use a remote reference for a file in another folder in the same repository, in an OAS3 definition file.
Run this action against that file.

Additional context
Source:

• $ref: '../../common/v0/schemas.yaml#components/schemas/example'

Output:

Error: Definition contains errors.
Error: Semantic error at paths./get.responses.200.content.text/plain.schema.items.$ref
Error: $ref paths must begin with #/

Look at the specification for remote references: https://swagger.io/docs/specification/using-ref/

Race condition exists when processing very large OAS files

Describe the bug
After reading the blog post, I was pretty excited to integrate this into my CI/CD pipeline. I had things up and running very quickly and the action was finding and reporting on the errors that prompted me to seek it out in the first place.

However, the next day we saw some suspicious results on a pull request that added a second OAS file to a project. The first commit showed legit failures. But a follow-up commit (that did not make changes to the OAS file) did not report failures. I was not able to get it to fail again.

I'm pretty sure the issue is that the action's hasErrors is returning before the editor has finished rendering the errors to the DOM. Unfortunately, I can't share the API file as it's a private API but I can say that it's about 4000 lines long, most of which are schema definitions (including some VERY large enums). When I paste it into the editor, there's a heartbeat or two before the errors appear in the page. I was also using the private docker method of running the action.

The errors that were not being reported were related to missing schema definitions.

To Reproduce
Steps to reproduce the behavior:

1. Setup swagger-editor-validate using the "private" method described [here](https://swagger.io/blog/api-design/validate-openapi-definitions-swagger-editor/.
2. Feed a LARGE OAS file into the action that references several missing schemas in API responses.

Expected behavior
Validation errors should be reliably reported.

• Version: v1.2.0.
• Platform: Ubuntu 18.04

Add support for https://editor-next.swagger.io/

Please, add support for https://editor-next.swagger.io/

It is required to validate OpenAPI 3.1 schemas. (https://editor.swagger.io/ is not compatible with OpenAPI 3.1)

folder as definition-file

folder support like definition-file ? :)

It would be nice to add this option

Semantic error is not reported

Describe the bug

The semantic error reported by SwaggerEditor website is not reported by the Github Action

To Reproduce
Steps to reproduce the behavior:

1. Define 2 endpoints
2. Set the same value inoperationId

Expected behavior
Semantic error at paths./.get.operationId
Operations must have unique operationIds.

Screenshots
N/A

Additional context
Add any other context about the problem here.

• Version: the latest release and the current master branch
• Platform: swaggerapi/swagger-editor

Support warnings

Is your feature request related to a problem? Please describe.

https://github.com/swagger-api/swagger-editor/blob/master/src/plugins/validate-semantic/validators/oas3/parameters.js

Describe the solution you'd like
A clear and concise description of what you want to happen.

Error: Unable to resolve action `char0n/swagger-editor-validate@v1`, unable to find version `v1`

Describe the bug

👋 I have the following in my github action:

jobs:
  validate-swagger:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Validate OpenAPI definition
        uses: char0n/swagger-editor-validate@v1
        with:
          definition-file: service.swagger.json

but when the action runs I get an error

Error: Unable to resolve action `char0n/swagger-editor-validate@v1`, unable to find version `v1`

I am not sure if I am doing something wrong?

To Reproduce

As above I suppose.

Expected behavior

I expect that github actions should resolve the action, send my swagger to https://editor.swagger.io/ for validation, and hopefully, in my case, fail validation.

Screenshots
If applicable, add screenshots to help explain your problem.

Additional context
Add any other context about the problem here.

• Version: v1
• Platform: github actions
• Subsystem:

Thank you!

Missing error description in v1.3.0

Describe the bug
Using the latest version (1.3.0) I cannot see the OpenAPI specification errors, only that an error occurred:

When I pin the version to 1.2.1 it works as expected:

(teamfolder is the name of the repository)

To Reproduce
Can't share the actual specification, but I expect it's not strictly necessary.

Expected behavior
@v1 (which as far as I know defaults to the latest, v1.3.0) outputs similar results to @v1.2.1

Platform
running the private use-case of the Github Action on ubuntu-latest (20.04 if I'm not mistaken)

Thank you for your work, really useful.

Providing definition as string

Is your feature request related to a problem? Please describe.
It should be possible to provide OAS definition as string.

Describe the solution you'd like
Introduce new input: definition

Additional context
definition and definition-file will not be required, but one of them would need to be defined, otherwise the GA will error.

Question: how does this compare to redocly-cli

I just discovered this action, before we used https://github.com/Redocly/redocly-cli in another CI system.

I assumed this would just be a wrapper around it, but instead it looks like you parse the html for errors from openapi-editor. What are the advantages of that / what is the reason you chose that approach?

Expose a screenshot on failure

Is your feature request related to a problem? Please describe.
Screenshot on failure provided by puppeteer

Describe the solution you'd like
Screenshot on failure provided by puppeteer

Providing definition as URL

Is your feature request related to a problem? Please describe.
It should be possible to provide OAS definition as URL.

Describe the solution you'd like
Introduce new input: definition-url

Additional context
definition-url and definition-file will not be required, but one of them would need to be defined, otherwise the GA will error.

Render success message in green color

Mechanism for ignoring errors

Is your feature request related to a problem? Please describe.
It is very common that OAS definitions contains errors when validated in https://editor.swagger.io/. There are cases there is nothing that authors can do with these errors and this errors are ignored.

Describe the solution you'd like
Introduce an ignore mechanism ideally in form of pluggable JavaScript file which has a default export a function that asserts if error should be ignored or not.

Describe alternatives you've considered
Using regex in workflow file

Additional context
We need to document and standardize our Error object shape.