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 content I wrote
A Technical Introducition to MathML Core for Writing Mathematics on the Web
- Programming, Mathematics
Thanks to recent efforts, all major web browsers currently support MathML Core, a subset of MathML focused on important presentation markup, to support mathematics on the web. As of this writing, the MathML Core specifications are still not finalized, but given its strong origins and support, it can…
The New Open Source Video Game Randomizer List Is Now Live
- Video Games, Programming
Time to update your bookmarks! After a few months of work behind the scenes, the new open source version of The BIG List of Video Game Randomizer is now live for your enjoyment, with dark mode support and a brand new UI for better readability! The new URL is: https://randomizers.debigare.com/ (The…
The Future of the Video Game Randomizer List
- Video Games, Programming, Anecdotes
It's hard to believe that it's been almost 8 years since I first posted on the ROMhacking.net forums a list of video game randomizers that I found online, and that it would evolve into the massive project it has become today, with almost 900 entries currently being listed. It's always a strange…
Minifying JSON Text Beyond Whitespace
- Programming, Mathematics
JSON is a common data serialization format to transmit information over the Internet. However, as I mentioned in a previous article, it's far from optimal. Nevertheless, due to business requirements, producing data in this format may be necessary. I won't go into the details as to how one could…
Current Generative AIs Have Critical Quality Issues
- Business, Quality Assurance, Security
The hype for generative AI is real. It is now possible for anybody to dynamically generate various types of media that are good enough to be mistaken as real, at least at first glance, either for free or at a low cost. In addition, the seemingly-creative solutions they come up with, and the…