TL;DR: During CI, I am generating a UML diagram out of the Swagger definition and I’m publishing it to Confluence.
At work, we use Swagger to define our REST APIs. With the swagger codegen maven plugin, we can generate a lot of code (models and interfaces for the controllers) as well as our API documentation. But a picture is worth a thousand words, so I wanted a way to automatically generate a UML diagram out of the Swagger definition.
With a little bit of investigation, I found Swagger to UML. It’s a small script written in Python which converts the Swagger definition into Plant UML diagrams. Plant UML then renders the diagram into PNG or SVG but it requires Graphviz to be installed.
There are a lot of moving parts here with various technologies. Swagger to UML needs Python. Plant UML needs Java and Graphviz. And I would like all these to run automatically during CI. Sounds like it’s time to bake a Docker image!
I created the swagger-to-diagram Docker image which assembles together:
- JRE 11
- Python 3
- Swagger to UML
- Plant UML
- a custom bash script to execute the above
With that Docker image in place, I can generate my PNG diagram like this:
docker run --rm -v $PWD:/data \
ngeor/swagger-to-diagram swagger2png.sh \
In Bitbucket Pipelines, that’s just an extra step definition:
name: Generate UML diagram from Swagger file
- swagger2png.sh ./src/main/swagger/swagger.yml diagram.png
And now, for the cherry on the top: I also added a script which publishes the PNG diagram as an attachment to Confluence Cloud. That’s the extra mile that makes the whole process more magic. And it’s just a
curl call to the Confluence Cloud REST API which creates or updates attachments.
The script is packaged in the same Docker image and you can call it like this:
put-confluence-attachment.sh -u $USERNAME:$PASSWORD \
--domain acme \
--content-id $CONFLUENCE_CONTENT_ID \
--comment "Attaching UML diagram" \
You’ll need a Confluence Cloud instance at
https://acme.atlassian.net/wiki (that’s the
domain parameter) as well as a username and password to access the REST API. You’ll also need a page to attach the diagram. That’s the
In my case, I have one Confluence page per microservice. When the build of a microservice succeeds, it updates the diagram on the microservice’s page.
Some practical tips:
- Don’t use your personal Confluence credentials. Instead, create a dedicated account for automations like these. This way you can control better the access rights of the account. Plus, it looks much more awesome to see that a page was changed by a bot.
- Store the Confluence credentials as global environment variables in your CI server, so that you don’t have to repeat them on each project.
- If you use a different Confluence page per project (that’s what I do), then you should store that page’s ID as a project environment variable in your CI server. You could, however, use a single page and just use a different filename per diagram.
In the end, you get a fancy diagram in Confluence:
Originally published at https://ngeor.com/2018/11/03/from-swagger-to-confluence-uml-diagrams.html on November 3, 2018.