rss resume / curriculum vitae linkedin linkedin gitlab github twitter mastodon instagram
Go Tip: Judging go-swagger with dredd
Apr 03, 2018

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:

  1. You will need to add the x-default vendor extension so the requests made by dredd work.
  2. Do not add the default annotation for the in-path parameters because that will make the generated document invalid when calling swagger validate.

Back to posts