E2E 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, E2E 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, if you are not using a version control system
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.
If you do not use a version control system, keep a change log table in package Use Cases, e.g. on a use case diagram called Change Log.
|2015-11-05||John Smith||ISS-1234: Correlation ID fix||Correlation ID changed to binary|
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 E2E Bridge.
See Documentation of an xUML Service for more information on that feature.