Martyice.github. IO/UML-in-post…

IO/martyice.github

Release time: September 4, 2018

The problem

You have an architectural idea in your head, but it’s hard to get it across. Team members have different ideas about the names of things, where they are, and how they fit together. Someone had erased the whiteboard (it wouldn’t be clear for a few days anyway). You’ve seen diagrams used elsewhere, but you don’t want to install crappy tools whose user interfaces are impossible (and what do the symbols mean anyway!). .

If you are in this situation, I encourage you to take a look at UML (Unified Modeling Language). It has recently become a useful tool for my belt, combined with the following enablers.

  • Plant UML – a free REST API that generates beautiful images from UML documents
  • Postman – An indispensable ecosystem for calling and testing HTTP APIs
  • Paint.Net – a free Windows application that is much better than MSFT Paint.

With the combination of these three things, I can quickly generate UML diagrams that describe in a single picture what laborious conversation (voice and text) cannot.

UML

As with any new language, UML can seem a bit confusing at first. Don’t get discouraged, it’s pretty simple, especially for “fast and dirty” use cases (which is usually how I use it). In general, you will add the following.

Start tag.

@start uml
Copy the code

Define your group and participants.

box "Picture" #LightGreen
	participant OnePicture
end box

box "Word" #LightBlue
	participant ThousandWords
end box
Copy the code

Define the interactions between the actors.

OnePicture -> ThousandWords : "Are we equal?"
ThousandWords -> OnePicture : "Yes."
Copy the code

Also, don’t forget your end UML tags.

@enduml
Copy the code

This simple example produces the “Picture is Worth a Thousand Words “diagram above!

Plant UML

Plant UML is a convenient service that generates SVG images from UML diagrams. In addition, they are well documented, providing both a high-level overview of UML functionality and details when you are ready to dive into the nitty gritty. This is a valuable resource for extending the UML learning curve. Below is the URL we used to generate the chart.

POST http://plantuml-service.herokuapp.com/svg
Copy the code

Postman

If you’ve developed web-based apis (REST, SOAP, etc.), Postman should need no introduction. If you haven’t used it, I highly recommend you check it out, it’s an irreplaceable part of my development toolbox. In addition to downloadable tools, their subscription service adds team sharing, documentation, and testing components that we use extensively at EarthClassMail.

To generate UML, we need to do two things.

  1. Fill in the POST in the Postman input URL (plantuml-service.herokuapp.com/svg)
  2. Paste our UML in the body.

The UML above produces the following easy-to-read diagrams.

To obtain the output

The last step is to pull your UML diagram out of Postman and into an image file, which, I admit, is a little strange. There are several different ways to accomplish this task. Both involve using the wonderful Paint.Net to actually save the output.

Poor man’s way

If your image is small enough (i.e. perfectly suitable for Postman’s output window), an easy way to do this is to take a screenshot (Ctrl-Alt-prtscn), paste it into Paint.Net, crop it accordingly, and save. Very simple.

More content

If your UML diagram exceeds the Postman output pane size, don’t worry, the following steps (which are a bit complicated) will allow you to save the complete output.

  1. In Postman, the “Send” button has a downward arrow. Click on it and select “Send and download”. This will cause Postman to save the result as an SVG file (which is the format returned by PlantUML).
  2. Now comes the weird part — converting SVG to something that Paint.Net can recognize (in this case, a PNG file). I use the handy SVGtoPNG website for this task. Maybe there’s a better way – it works for me 🙂
  3. Once you have PNG, you can open it in Paint.Net, crop/trim/highlight/annotate it, and you’re done

UML-ing the Night Away

Hopefully, this short tutorial will inspire you with confidence to embark on an amazing UML journey. You will no longer be bound by the shortcomings of human language! Let the machine lead you through technical communication. Let the machine lead you to the nirvana of technological communication!

www.deepl.com translation