The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs. This allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
An OpenAPI definition can then be used by documentation-generation tools to display the API, code generation tools to generate servers, and clients in various programming languages, testing tools, and many other use cases.
I took the above description, of what OpenAPI is, directly from its specification. If you're one of the people that writes OpenAPI definition by hand in Swagger Editor, then this article was written just for you.
A couple of years ago I worked with a company called Ubiquiti Inc. We were producing great wireless hardware solutions with embedded UIs. I was fortunate to have joined the company in times when a cross hardware configuration system called UNMS was being architected and developed. The back-end part of the system consisted of a huge REST API layer that the front-end layer was consuming. We used a design-first approach of producing the API.
The workflow of this approach consisted of the following steps:
- Create changes in the OpenAPI 2.0 definition using Swagger Editor
- Issuer: issue a GitHub Pull Request for the team to review how new API endpoints could look
- Reviewer: paste the OpenAPI definition from Pull Request to Swagger Editor to see if errors were introduced
- Merge Pull Request
- Implement the actual REST API defined in OpenAPI definition
Today I'd immediately think about how to automate this workflow and make Continuous Integration do the work for us. Unfortunately, at that time my knowledge of CI/CD pipelines was limited and I wasn't fully aware of benefits and values CI/CD provides.
Some time has passed since then. I did my homework and studied the CI/CD topic thoroughly. I became a huge fan of GitHub Actions and automatization. Let's try to automate the workflow described above, using GitHub Actions.
Technical Design
We need to produce a GitHub Action that uses Swagger Editor to validate OpenAPI definition provided as a parameter to that action.
Using a Swagger Editor in GitHub Action can be achieved in two ways: running it in a docker container using swaggerapi/swagger-editor image, or using https://editor.swagger.io/ directly. Now that we have Swagger Editor running, we use Puppeteer to open a headless version of Chromium Browser, paste OpenAPI definition into the Swagger Editor, and wait for it to render errors (if the definition is valid, no errors will be rendered). Read errors from the Swagger Editor using Puppeteer and represent them via the GitHub Actions API. GitHub Action will report failure on any error, or success if the document is valid and contains no errors.
Why use Swagger Editor and not just JSON Schema validation? Well, Swagger Editor does add it's own additional layer of error recognition on top of JSON Schema validation. Unfortunately, this additional layer is tight coupled to Swagger Editor code, and the easiest way to use it is to use it via running the Swagger Editor in browser.
Implementation
The implementation wasn't as straightforward as I expected. But I still managed to implement this GitHub Action against the technical design mentioned earlier, with all its requirements. I called it swagger-editor-validate.
Usage
There are two major use-cases of how to use this GitHub Action, but both of them use the fact that your definition file lives in your GitHub repository. You just need to provide a file system path to it.
Public use-case
If you have access to the internet and don't mind that this GitHub Action sends your OpenAPI definition to https://editor.swagger.io/ for validation, then use this workflow.
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 OpenAPI definition may contain sensitive information, use the following workflow. The workflow uses a Swagger-editor docker image that runs as a 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
This is what you'll see if your OpenAPI definition validates successfully.
This is what you'll see if your OpenAPI definition contains errors.
Future
During implementations I identified other features that this action would benefit from. In order to not the extend the implementation scope of the first version, I decided not to implement these features, but rather document them and implement them later. These features include:
I think the most interesting one is mechanism for ignoring errors. It is very common that OpenAPI definitions contain errors when validated in https://editor.swagger.io/. There are cases when there is nothing authors can do with these errors, and these errors are known and ignored. This will open a door for such a use-case, which I'm sure is quite common.
I Hope that swagger-editor-validate will become a handy tool for anybody using Swagger Editor to edit OpenAPI definitions. I do know it will become handy for my old team in Ubiquiti Inc ;]