Using go-swagger it’s great for automatically generating Swagger 2.0 documentation for your API from annotations in your code. It even includes a validator to make sure the generated swagger.json
is valid:
swagger validate swagger.json
However there’s a tiny thing about this generated file, even if the swagger.json
(or Blueprint) file is 100% valid it may not represent your real implementation, think of typos, broken responses, missing parameters or incorrect status codes.
Shocking right?!
Enter dredd:
Language-agnostic command-line tool for validating API description document against backend implementation of the API.
Dredd supports both Swagger and Blueprint as API Description formats, it has a plethora of supported hook languages, installation and usage is pretty straight-forward. To install it you will need NodeJS and a recent Python (3.0+), however you can always use Docker instead:
Using it is as simple as:
dredd <path-to-swagger.json> <backend-handlind-the-requests>
Word of advice when interacting with Swagger’s in-path parameters:
- You will need to add the
x-default
vendor extension so the requests made by dredd work. - Do not add the
default
annotation for the in-path parameters because that will make the generated document invalid when callingswagger validate
.