1st part of this post can be found here.
Document your API - Swagger
Ok, doctest was for Elixir & Python. Many other languages / platforms have similar mechanisms at the various stage of maturity, but things get even better once you focus on documentation of your public API, especially if you're using open standards - like RESTful services or WS. In such a case, you've plenty of solutions to choose from. One of them is swagger.io.
What's Swagger? If I had to invent a one-liner for it, I'd say that ...
Swagger is an API specification "guardian" ;)
You can use it:
- as a tool formalize & document your API (formalizing = making it testable as well, ain't it?)
- as a codegen tool to create SDKs out of your API (which may be controversial, I know) - there are plenty of platforms supported
What's really cool, Swagger doesn't just provide a neat way to browse API docs, it's also able to:
- let you try API directly from documentation screen in your browser (!)
- validate whether the specification published is still up-to-date (!!) - check the demo here (look at the bottom right corner for R-T indication).
Swagger specs are written in YAML - honestly, I've never tried doing this on my own, so I don't know the actual hassle. Anyway, I know it can be auto-generated as well, but I didn't try it either.
Document your Arch - Structurizr
At last but not least, another interesting idea: Structurizr. It's a beloved child of Simon Brown - smart guy who's got some recognition as a frequent tech conference speaker & an author of pretty popular book - "Software architecture for developers". Simon's a bit obsessed (in a positive way) about architecture, it's maintenance & mutual correspondence to the actual code that implements this architecture.
Regarding architecture & its document, hopefully we all agree that:
- we need a way to document architecture on the level above low-level code constructs for the sake of clarity & to help with sharing the same vision (on multiple levels of abstraction) of the way systems is (& will be in future) built
- there's no better way to document architecture than good diagrams -> it doesn't have to be any ultra-sophisticated notation, quite the opposite: the simple the better (but still it has to be descriptive)
Simon claims (& I totally agree with him here) that there's no better way to keep diagrams in-sync with code than either generate them from code directly or from metadata that comes with this code. His tool (Structurizr) uses the mix of those two (for top layers of his C4 model he uses meta-code: additional code that doesn't play any functional role, but defines architecture for documenting purpose, for component layer he uses reflection) & he calls this approach "software architecture as code". Here are some examples.
To be honest, I'm skeptical. Code needed to note the architecture down is used just for that -> diagrams are not "side effects" of working functional code, it's just an additional notation: instead of using a graphical tool, you use the programming language of your choice. It's definitely easier to track changes that way, but if you forget to update the description, there are no consequences.
Pic: © Nomad_Soul - Fotolia.com
