The Builder provides several documentation features to support different kinds of users:
- modelers who want to modify the service and need a quick overview on the service's use cases, backend access and data structures
- service consumers who want to call the service and need information on the service interface
- Bridge operators who need a basic understanding of the service's purpose and features.
For these documentation purposes, the Builder offers the possibility to add documentation and comment tags to model elements.
How to Add a Documentation Tag
Lookup the element you want to add documentation to in the containment tree or diagram and open the specification dialog by right-clicking the element and selecting Specification from the context menu.
|Click Documentation/Hyperlinks and start typing in the documentation field.|
|By checking HTML, you can also insert HTML formatted documentation.|
By clicking, you can open an advanced HTML editor that has more formatting options and also allows to edit the HTML directly.
How to Add Comment Tags
Lookup the element you want to add a comment to in the containment tree and select Create Element > Comment from the context menu. Simply start typing to add the comment. Comments can be plain text only.
Service Documentation for Modelers
To give modelers a good overview on the service we recommend to
- provide an overview on what the service does by drawing a use case diagram
- show the main data structures and relations by drawing a class diagram
- give an overview on the main backend processing by drawing a sequence diagram
- provide a change log in the xml file that is displayed on the Bridge
Use Case Diagram
Draw a simple use case diagram describing the main actors and main processing in a package called e.g. Use Cases.
We also recommend to make the documentation that previously has been added to the Data package visible by adding it to this diagram.
You can do this as follows:
|Go to the specification dialog of the Data package and select the documentation element.|
|Drag and drop it to the diagram pane.|
You can define to not display stereotype <<documentation>> (like shown above) via the symbol properties from the context menu.
Draw a sequence diagram to give an overview on the main backend processing.
Keep a change log table in package Overview. Builder 7.4.0 The Builder templates already provide a simple change log table in a use case diagram Overview.
All information provided here will be visible in the service documentation on the Bridge for Bridge operators to see (see Service Documentation for Bridge Operators below).
If this default change log table does not suit your needs, you can change it for dedicated models, or you can change the template itself. By changing the template, you can get consistent change logs throughout all services.
To edit the template, open file <your user directory>/.e2ebuilder/modelDocumentationTemplate.html with an editor. This file contains the HTML layout of the change log table:
Change the table or adorn the HTML with styling as you need.
Draw class diagrams for the main structures in dedicated packages (see Containment Tree Organization).
Service Documentation for Service Consumers
MagicDraw provides the possibility to add documentation and comment tags to model elements. Documentation and comment tags added to service model elements (service, operation, parameter) are explaining the service interface. They are meant to be read by the service consumer and will be generated to
- to the YAML file for REST services
For more information see REST Interface Documentation and Tags.
the WSDL file for SOAP services
Service Documentation for Bridge Operators
Like with all other model elements, you can also add documentation to the Data package. This documentation will be available for reading and editing on the Bridge.
See Documentation of an xUML Service for more information on that feature.
If service modelers provided a change log table with their deployed services, this change log will be visible in the Model Notes section of the Documentation tab.