DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Last call! Secure your stack and shape the future! Help dev teams across the globe navigate their software supply chain security challenges.

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Releasing software shouldn't be stressful or risky. Learn how to leverage progressive delivery techniques to ensure safer deployments.

Avoid machine learning mistakes and boost model performance! Discover key ML patterns, anti-patterns, data strategies, and more.

Related

  • The Unspoken Rules of Coding for Both Novice and Sage Developers
  • Vibe Coding With GitHub Copilot: Optimizing API Performance in Fintech Microservices
  • Unlocking AI Coding Assistants Part 3: Generating Diagrams, Open API Specs, And Test Data
  • Soft Skills Are as Important as Hard Skills for Developers

Trending

  • AI’s Role in Everyday Development
  • AWS to Azure Migration: A Cloudy Journey of Challenges and Triumphs
  • How Trustworthy Is Big Data?
  • Beyond Code Coverage: A Risk-Driven Revolution in Software Testing With Machine Learning

Coding the Documentation with Structurizr

Structurizr is a tool which allows you to document your software architecture using regular Java code and a bit of Markdown/AsciiDoc.

By 
Grzegorz Ziemoński user avatar
Grzegorz Ziemoński
·
May. 17, 17 · Tutorial
Likes (8)
Comment
Save
Tweet
Share
12.3K Views

Join the DZone community and get the full member experience.

Join For Free

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 in checking it 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:

    <dependencies>
        <dependency>
            <groupId>com.structurizr</groupId>
            <artifactId>structurizr-core</artifactId>
            <version>1.0.0-RC3</version>
        </dependency>
        <dependency>
            <groupId>com.structurizr</groupId>
            <artifactId>structurizr-annotations</artifactId>
            <version>1.0.0-RC3</version>
        </dependency>
    </dependencies>

    <repositories>
        <repository>
            <id>jcenter</id>
            <url>http://jcenter.bintray.com</url>
        </repository>
    </repositories>


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:

public class HelloWorld {
    private static final String API_KEY = "your-api-key";
    private static final String API_SECRET = "your-api-secret";
    private static final int WORKSPACE_ID = 0; // your workspace ID

    public static void main(String[] args) throws Exception {
        Workspace workspace = new Workspace("My First Workspace", "I'm using this to learn about Structurizr");
        Model model = workspace.getModel();
        ViewSet viewSet = workspace.getViews();

        Person me = model.addPerson("Me", "Myself.");
        SoftwareSystem world = model.addSoftwareSystem("World", "Earth, to be precise.");

        me.uses(world, "Hello, World!");

        viewSet.createSystemContextView(world, "My First View", "Just me and the world.").addAllElements();

        StructurizrClient structurizrClient = new StructurizrClient(API_KEY, API_SECRET);
        structurizrClient.putWorkspace(WORKSPACE_ID, workspace);
    }
}


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 three classes to our project:

@Component
@UsesSoftwareSystem(name = "Mail Server", description = "Send emails.")
public class MailComponent {
}
@Component
public class TwitterComponent {
    @UsesComponent(description = "Send an email about a Twitter update")
    private MailComponent mailComponent;
}
@Component
public class FacebookComponent {
    @UsesComponent(description = "Send an email about a Facebook update")
    private MailComponent mailComponent;
}


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.

public class HelloAnnotations {
    private static final String API_KEY = "your-api-key";
    private static final String API_SECRET = "your-api-secret";
    private static final int WORKSPACE_ID = 0; // your workspace ID

    public static void main(String[] args) throws Exception {
        Workspace workspace = new Workspace("My First Workspace", "I'm using this to learn about Structurizr");
        Model model = workspace.getModel();
        ViewSet viewSet = workspace.getViews();

        model.addSoftwareSystem("Mail Server", "Allows sending emails.");
        SoftwareSystem spammingSystem = model.addSoftwareSystem("Spamming Software System", "Sends you a ton of useless emails.");
        Container spammingApp = spammingSystem.addContainer("Spamming Container", "Sends you a ton of useless emails.", "Java");

        ComponentFinder componentFinder = new ComponentFinder(spammingApp, "com.tidyjava.examples", new StructurizrAnnotationsComponentFinderStrategy());
        componentFinder.findComponents();

        viewSet.createComponentView(spammingApp, "Spamming View", "All the spam in the world.").addAllElements();

        Styles styles = viewSet.getConfiguration().getStyles();
        styles.addElementStyle(Tags.COMPONENT).background("#1168bd").color("#ffffff");

        StructurizrClient structurizrClient = new StructurizrClient(API_KEY, API_SECRET);
        structurizrClient.putWorkspace(WORKSPACE_ID, workspace);
    }
}


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:

Summary

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!

Software documentation Coding (social sciences)

Published at DZone with permission of Grzegorz Ziemoński, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • The Unspoken Rules of Coding for Both Novice and Sage Developers
  • Vibe Coding With GitHub Copilot: Optimizing API Performance in Fintech Microservices
  • Unlocking AI Coding Assistants Part 3: Generating Diagrams, Open API Specs, And Test Data
  • Soft Skills Are as Important as Hard Skills for Developers

Partner Resources

×

Comments

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends: