Coding the Documentation with Structurizr

Regardless of whether we like it or not, software documentation is needed, useful, and often even required. I don’t know about you, but I hate going to the company’s Wiki and updating documentation pages every time we change something in the code, database or the like. Structurizr is one of the tools that I’ve heard about for a long time and somehow I’ve been slacking to check out. I finally decided to give it a try and here I am, writing a short introduction so you guys can take advantage of it as well.

About Structurizr

As the tool’s page nicely informs us, “Structurizr is a collection of cloud (software as a service) and on-premises tooling to visualize, document and explore your software architecture.”

Yes, I know. That’s Marketish and we don’t speak that. Translating it into Programmish, Structurizr is a tool which allows you to document your software architecture using regular Java code and a bit of Markdown/AsciiDoc. (Actually, not only Java, but we don’t care.) Once you do so, you upload this documentation to a web application that renders a nice architecture diagram for you.

Hello, World!

To get yourself started with Structurizr, you will need a free account. You can create one here.

Once you’re logged in, you need to locate the “Create a new workspace button” and click that. When the page reloads, you should see your brand new workspace just below the buttons:

We can finally get into the promised code part. Create a new Maven project and add the following lines to the pom.xml:

The first dependency contains the core functionality of Structurizr. The second one drags in the annotations that we will later use to automatically generate a components diagram of our “system”. We also need to add the jCenter/Bintray repository as Structurizr is not available in Maven Central.

Once we have that, let’s create a HelloWorld class like this:

That may seem like a lot of code but it should be pretty straightforward to understand. We’re creating an object representing the workspace that we’ve just set up online. After that, we’re filling the workspace’s model with a single person (“me”) and a single software system (“world”). Next, we’re specifying that the person uses the system with a description “Hello, World!” and creating a context view. As the last step, we’re uploading the whole workspace using a provided API client.

Remember to replace the constants on the top of the class with your own API key, secret, and workspace ID. You can find this information by clicking the “More details…” button on your newly created workspace. After that, you can run the program.

Once it finishes, you can click on your workspace in the web interface and you should see a diagram like this:

Hello, Annotations!

We’re by no means trying to compete here with the great Structurizr documentation prepared by Simon Brown, but for the sake of getting you interested in the tool, let’s generate another diagram. This time, we’ll use annotation scanning to automate the process a bit. Add the following 3 classes to our project:

These classes are not the most useful, but that’s not the point. We’re using Structurizr annotations to denote components present in our system and their interdependencies. We can also specify dependencies to external systems as in the MailComponent example.

With this in place, we can configure Structurizr to scan for the annotations. It’s just a minor change of the code we used for the “Hello, World!” example.

This time we created two software systems in our model – a mail server and a spamming system. The spamming system consists of a single container, being just our Java application. Next, we set up a component finder that does the job of identifying the components and their relationships for us. After that, we create a view and add a bit of style, so that our diagram is less dull than the previous one. And as the last step, we upload the workspace using the client.

Again, remember to replace the constants on the top of the page. This time, you also need to replace “com.tidyjava.examples” with whatever package you’re keeping your components in. After running the program and refreshing the workspace, you should see something like this:


Structurizr is a really nice tool and I’m glad I finally gave it a try. The idea of generating the documentation straight from the code seems very compelling to me and I’d be glad to see more tools like this available for developers. If you’re willing to learn more about Structurizr, as I certainly do, you can visit its page and its Java-ish documentation. Happy documenting coding!

About the Author Grzegorz Ziemoński

King of Tidy Java, nerd that thinks about producing perfect software all the time and proud owner of 2 cats.

follow me on: