Validating and Viewing OpenAPI Definitions with Docker
- Quality Assurance, Programming
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-uiRelated articles I wrote
Scrum Is Not Agile
- Programming, Business, Psychology
While there is no denying that Scrum revolutionized the software industry for the better, it may seem a little strange to read about someone that dislikes it despite strongly agreeing with the Agile Manifesto, considering the creator of Scrum was one of its signers. However, after having experienced…
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…
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…
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…
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…