Open API Diagram

OpenAPI Specification (formerly known as Swagger) is a widely-used specification for building and documenting RESTful APIs. One of the key features of the OpenAPI specification is the ability to describe the structure and behavior of an API using a variety of elements, such as paths, parameters, and responses. One way to visualize and understand these elements is through the use of diagrams, which can provide a visual representation of the API's structure and behavior.

When creating Open API diagrams, you can use a variety of stereotyped elements to represent the different components of the API:

• Schema - represents a data structure, such as an object or array, that can be used in the API.
• Server - represents the server or servers that the API is hosted on.
• Path - represents a specific endpoint or resource in the API, such as "/users" or "/users/{id}".
• Parameter - represents a parameter that can be passed to the API, such as a query parameter or path parameter.
• Get, Post, Put, Delete, Head, Options, Patch, Trace - represent the different HTTP methods that can be used to interact with the API.
• Request Port and Response Port - These elements represent the ports that the API uses to receive requests and send responses.
• Request Body - represents a connector that connects the request body port with the schema of the request, such as a JSON object.
• Response - represents a connector that connects the response port with the schema of what the API returns, such as a JSON object.
• Schema Component, Security Schema Component, Parameter Component, Response Component, Request Body Component, Header Component, Example Component, Link Component, Callback Component - These elements are the component elements that are used to describe the API in more detail.

Path Element

The Path element in Open API diagrams, derived from UML activity elements, is used to represent the endpoint of an API. It can have other nested elements, such as Get, Post, Put, Delete, Head, Options, Patch, and Trace, which are represented as activity elements with the appropriate stereotype and have request and response ports.

To construct the Path element in the diagram editor, you can start by dragging the Path element from the toolbox onto the diagram canvas. Then, you can add the desired nested elements (Get, Post, etc.) by dragging them from the toolbox and dropping them over the Path element.

You can also customize the properties of the Path element, such as its name and documentation. The name can be edited directly in the diagram editor, the Documentation sidebar can be used for editing the documentation. You can also use the Properties window.

You should specify the name of the Path element, such as "/users", to represent the endpoint or route of the API.

Additionally, you can add parameters to the path by dragging the Parameter element from the toolbox and dropping it over the Path element. The Parameter nodes are attached to the border of the Path element.

Path element (in the OpenAPI diagram)

Response

The response connector is a specialized connector element in the OpenAPI diagram that is used to specify the response code and connect it to the appropriate response schema. To use the response connector, you would first need to create a response schema element (which is a stereotyped class element with the ​schema stereotype). This element represents the structure of the response that the API will return to the client. Once you have created the response schema element, you can then create a response connector element by choosing the Response connector tool in the toolbox and then start dragging from the Response port to the appropriate Response schema in the diagram canvas.

When creating the response connector, you will need to specify the response code as the name of the connector. For example, if the API will return a "200 OK" response, you would name the connector "200". You can also specify additional details such as the response description, and examples using the Documentation sidebar.

You can use the standard response codes such as:

• 200 OK - The request was successful.
• 201 Created - The request was successful, and a resource was created as a result.
• 204 No Content - The request was successful, but there is no representation to return (i.e. the response is empty).
• 400 Bad Request - The request could not be understood or was missing the required parameters.
• 401 Unauthorized - Authentication failed or the user does not have permissions for the requested operation.
• 403 Forbidden - Authentication succeeded, but the authenticated user does not have access to the requested resource.
• 404 Not Found - The requested resource could not be found.
• 406 Not Acceptable - Indicates that the server cannot produce a response matching the list of acceptable values defined in the request's headers (For example, a client may send an "Accept: application/json" header, but the server may only be able to produce XML-formatted responses.)
• 500 Internal Server Error - An error occurred on the server.
• 503 Service Unavailable - The server is currently unable to handle the request (i.e. due to maintenance or capacity issues).

Request Body

The Request Body connector is a type of relationship connecting the request port with the request body schema element. The request body schema element is where the request payload information is defined, and the request port is where the endpoint that the request will be sent is specified. The request body connector is used to link these two elements and provide a complete picture of the request being sent to the API.

The Request Body Schema element includes a number of different fields that describe the request payload, including its type, format, and any constraints or limitations on the data that can be included. By having the Request Body schema element defined, the API can ensure that all requests sent to the endpoint are in the correct format and contain the required information. This helps to prevent errors and improve the reliability of the API.