Page History
Div | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
REST Interface Documentation and Tags
Documenting REST Operations
When compiling a REST service, an OpenAPI descriptor file is created that contains the service description. This file reflects the REST interface structure as implemented by you.
Note | ||
---|---|---|
| ||
REST resources are generated with their class name only, instead of their fully qualified name (including the xUML package structure, like |
The generated OpenAPI file also contains textual documentation. You can add this textual documentation to the following model elements:
- REST port type
- REST method
- method parameters
- REST error class
Figure: Specification Dialog of a REST Method
The documentation from the model elements will be added to the description and summary tag of the service descriptor:
Panel | ||||
---|---|---|---|---|
| ||||
swagger: '2.0' basePath: /support [...] paths: [...] /supportcases/: get: summary: Query support cases by status and customer name. description: Query support cases by status and customer name. parameters: - name: status in: query description: (_Optional_) Status the selected support cases should be in. type: string required: false - name: customerName in: query description: (_Optional_) Name of the customer who's support cases should be selected. type: string required: false responses: 200: description: A list of support cases that correspond to the query. schema: title: supportCases $ref: '#/definitions/urn:Services.SupportCase.Classes.ListOfSupportCases' default: description: "400 - Logical error, Bad Request / \n404 - Technical error,\ \ Not Found / \n500 - Technical error / \n\_\n(See message string for\ \ error details.)\n" schema: $ref: '#/definitions/urn:Services.SupportCase.Classes.RESTError' [...] |
While writing the documentation, you can use plain text or Git flavored markdown. Do not use HTML mode in MagicDraw while adding documentation.
Tools supporting OpenAPI descriptor files (yaml format) can make the documentation visible:
Tagging REST Operations
You can use <<RESTOperationTag>> to group your operations. The E2E REST Test Tool will then display the operations in groups by tag. Operations without a tag assigned will appear under group "default".
Figure: REST Operation Groups
At the very bottom you can also find the base URL and the API version.
To tag a REST operation, create a new <<RESTOperationTag>> and draw a class diagram to connect it to operations via a <<use>> dependency.
Figure: Tagging REST Operations
Artifact <<RESTOperationTag>> has the following tagged values:
Multiexcerpt include | ||||
---|---|---|---|---|
|
For a better overview, we recommend to put all tag definitions in a separate package and to create a separate class diagram for each tag:
REST Response Definitions
All (default and specific) error classes are reflected in the OpenAPI file of the service as responses.
Panel | ||||
---|---|---|---|---|
| ||||
swagger: '2.0' [...] /supportcases/{id}: delete: description: Close a specific support case. parameters: - in: path name: id required: true type: string responses: '200': description: '' schema: $ref: '#/definitions/ResolveMessage' '401': description: |- - 401 - Unauthorized - 404 - Technical error, Not Found (See message string and additionalInfo for error details.) schema: $ref: '#/definitions/RESTErrorPlus' default: description: |- - 400 - Logical error, Bad Request - 404 - Technical error, Not Found - 500 - Technical error (See message string for error details.) schema: $ref: '#/definitions/RESTError' summary: Close a specific support case. tags: - Transition Support Case [...] |
In the example OpenAPI file above you can find three responses for operation delete. The responses are sorted by HTTP status code.
Status Code | Description | Response Class |
---|---|---|
200 | normal response | ResolveMessage (REST Parameter) |
401 | specific error response for authorization errors | RESTErrorPlus |
default | default error response | RESTError |
The E2E OpenAPI Importer will import these definitions to the calling service as defined in the OpenAPI file.
...
icon | false |
---|
...