Code docs that make sense - part II

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

3 years ago

Latest Post On Meditation. And Mindfulness. by Sebastian Gebski

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:

What's really cool, Swagger doesn't just provide a neat way to browse API docs, it's also able to:

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:

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

Sebastian Gebski

Published 3 years ago

Comments?

Leave us your opinion.

Subscribe our newsletter

Recieve news directly to your email.

No Kill Switch © 2018.