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
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…
Current Data Serialization Formats May Be a Waste of Money
- Programming, Business
Storing data. Transmitting data. Processing data. These fundamental topics of computer science are often overlooked nowadays thanks to the historical exponential growth of processing power, storage availability and bandwidth capabilities, along with a myriad of existing solutions to tackle them. So…
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…