We use the free draw.io tool to produce all the diagrams for our website and presentations. Following the process outlined below, the draw.io files are stored as XML, which means it is easy to manage them in git.
The tool can be run from the browser, or as a desktop tool. We recommend the desktop tool if you are doing editing of the diagrams because it supports auto-save.
Opening multiple diagrams
Whenever you start draw.io, it offers the choice to either open a new diagram or an existing file. On the desktop, New... means new window, and you can use it to have multiple files open at once.
Export new diagrams as an SVG, including a copy of the diagram
The following instructions must be followed to maximize diagram maintainability.
To save a new diagram, choose File -> Export as -> SVG...
Ensure the Include a copy of my diagram box is ticked, and tick the Transparent Background box as well:
This will ensure that:
- the output renders nicely at all sizes in any modern web browser (no image artifacts, especially on text)
- the diagram is entirely self-contained, and can continue to be edited and evolved in draw.io
- each diagram is version-controlled in git as its own independent XML file
- subsequent changes to the diagram can just directly edit this SVG file (no further Export as needed)
As indicated above, to edit existing SVG diagrams, you should be able to simply:
- open them directly in draw.io
- make any changes directly to the diagram
- save the file (no Export as needed)
Swagger automatically generates a website that documents the REST APIs supported by the OMAG Server Platform. It is based on the Open API Specification (V3) .
The website is found at
<serverURLroot> is the location of the OMAG Server Platform (for example,
The top of the page gives a general description of the OMAG Server Platform plus a link to more documentation.
The content for this header is located in the OMAGServerPlatform.java file that provides the
main() method for the OMAG Server Platform.
Swagger annotations in
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
Beneath the header is a list of the platform's REST APIs. This is the definition for the operational services that are part of the administration services:
The REST API operations are grouped into services by the following
@Tag annotation that appears in each Spring resource bean that is part of the service. If the name of the
@Tag matches then the operations in the resource beans are all part of the same service.
Swagger annotations in OperationalServicesResource.java
1 2 3 4 5
Further information can be provided for each operation. This is one of the operational services operations:
This is added to the spring resource bean using the
1 2 3 4
Raise an issue or comment below