Validating and Viewing OpenAPI Definitions with Docker

- Quality Assurance, Programming

Assembled cog wheels

Here are a few commands I crafted to validate and easily read API definitions in the OpenAPI format, using Docker and open source tools provided by Swagger. I have yet to convert them into proper shell scripts, but I hope these will be helpful nonetheless.

The commands are designed to be run in a Linux shell, including under Windows Subsystem for Linux. Also, the OpenAPI definition will be assumed to be named openapi.json or openapi.yaml, depending on the file format used, and be located in the current directory the commands are to be executed.

Before doing any of the following, make sure to install Docker, and to start the service using the following command:

sudo service docker start

Validation

First, download the Swagger Badge Validator microservice image:

docker pull swaggerapi/swagger-validator-v2

Next, start the microservice; this will use port 8080 on your machine:

docker run --detach --name swagger-validator-v2 --publish 8080:8080 swaggerapi/swagger-validator-v2

You are now ready to send a request to the microservice to validate it.

JSON case:

curl --request POST http://localhost:8080/validator/debug --header "Accept: application/json" --header "Content-Type: application/json" --data-binary @openapi.json

YAML case:

curl --request POST http://localhost:8080/validator/debug --header "Accept: application/json" --header "Content-Type: application/yaml" --data-binary @openapi.yaml

This will return a JSON object. If the object is empty, the validation passed, otherwise it will contain a list of errors.

Once you're done, you may stop and remove the microservice:

docker stop swagger-validator-v2
docker rm swagger-validator-v2

Viewing

First, download the Swagger UI microservice image:

docker pull swaggerapi/swagger-ui

Next, start the microservice; this will use port 80 on your machine.

JSON case:

docker run --detach --env SWAGGER_JSON=/ext/openapi.json --mount type=bind,src=$PWD,dst=/ext --name swagger-ui --publish 80:8080 swaggerapi/swagger-ui

YAML case:

docker run --detach --env SWAGGER_JSON=/ext/openapi.yaml --mount type=bind,src=$PWD,dst=/ext --name swagger-ui --publish 80:8080 swaggerapi/swagger-ui

You may now read the OpenAPI definition in Swagger UI by opening the following URL:

http://localhost/

Once you're done, you may stop and remove the microservice:

docker stop swagger-ui
docker rm swagger-ui

Related articles I wrote

Radiating business woman

Essential International Standards and Registries for Web Developers

- Programming, Quality Assurance, Security

The following is a collection of free international standards, registries and references that I collected throughout the years while developing websites and web services. These references, while very precise and technical by their nature, are extremely useful in order to ensure that a specific…

Spaceship flying over active volcanoes

A Universe and World Creation Script for Mongoose Traveller 2nd Edition

- Tabletop RPGs, Programming

The following is a Python script developed by yours truly to generate a sector according to the core rulebook of the Mongoose Traveller 2nd Edition tabletop RPG, exactly as described in the Universe and World Creation chapter. It is designed to describe worlds in human-readable format as much as…

Medusa in fiery scenery

Deep Learning in Python with PyTorch - Tutorial and Demo

- Programming, Mathematics

As I am continuing my personal journey into deep learning research and development, I wanted to try out PyTorch, a machine learning framework with GPU acceleration primarily designed for the Python programming language. However, I couldn't find any good introductory resource online for it. So I read…

Dusty light bulb lying on the floor

Stop! Your Ideas Are Stale!

- Business, Programming

"Everything must be done now. Let's re-use existing proven solutions and build over them so we don't waste time." And thus, people will look at the top 2 or 3 most popular solutions they already know about or can easily find on the Internet, compare them, pick the best one, and maybe add or change…

Wii RVT-R Reader test kit

The Test Case That Bricked a Wii Test Kit

- Anecdotes, Quality Assurance, Video Games

Back when I was working at Eidos Montréal, part of my responsibilities included ensuring that the games we were producing for the Wii followed Nintendo's Wii Programming Guidelines. This is the story of how I bricked a Wii RVT-R Reader test kit by doing my job…

See all of my articles