About 2 years ago (give or take), I introduced nit, our Opinionated Go linter for code organization in-file, and then a few months later the MVP version was released, since then we have been using nit successfully to keep our code consistent.

However, there’s another tiny thing we haven’t been enforcing automatically: the rules we follow when generating our Swagger 2.0 documentation. For a little bit of more context we have been using go-swagger for years already, but this linting process is not exclusive to that package, it is more related to the swagger.json file that is generated after we annotate our code with the corresponding go-swagger metadata, the one meant to be shared with your customers.

We haven’t been enforcing it until now. Let me introduce to you: swagger-lint our opinionated linter for Swagger 2.0 specs.

What is swagger-lint?

swagger-lint is linter that enforces the conventions we follow when defining new resources, new models and the naming of those. The rules are pretty straightforward and the actual code of this linter is not complicated at all.

Version v0.0.1 is the most recent one, and although it’s the first version, it is consireded stable and ready to use for production.

Installing and Using

You can download the released binary from the releases page, or you can do:

go install github.com/MarioCarrion/nit/cmd/nit

Or use the tools.go paradigm:

// +build tools

package tools

import (
	_ "github.com/MarioCarrion/swagger-lint"
)

To use it:

swagger-lint -input path/to/swagger.json

If there are any violations it will print them out including specific details of why it was considered a violation.

Conclusion

This tool allows us to yet again make sure our code is consistent across all our projects, and although the tool is really simple in its implementation what matters here is that we have concrete rules that everybody agrees on, follows and can be enforced via automatic builds, and that is the key takeaway: if you have rules or conventions, make sure those can be enforced every single time a line of code is committed to the repository.

Back to posts