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.
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.
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
// +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.
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.