How to Import and Export OpenAPI

Turn an OpenAPI description into a class diagram, and a class diagram back into an OpenAPI description.

Import an OpenAPI description

In the Project Explorer, select the folder the new diagram should go into (or a diagram in that folder).
Choose Diagram → Import → OpenAPI…
Pick an OpenAPI 3.0 or 3.1, or Swagger 2.0, file (.yaml, .yml or .json).

A class diagram is added and laid out automatically. The import lists anything it could not keep.

Export a class diagram as OpenAPI

Select a class diagram in the Project Explorer. If it is open, it is exported as shown.
Choose Diagram → Export → OpenAPI…
Enter the API's title (the diagram name by default) and version.
Choose the file. Its extension picks the format: .yaml / .yml for YAML, .json for JSON.

The file is written as OpenAPI 3.0.

How OpenAPI maps to the diagram

OpenAPI	Class diagram
Object schema (`components/schemas`)	Class; its properties are attributes
Schema with `enum`	Enumeration; the values are its literals
`allOf` with a `$ref`	Generalization to that schema
Property referring to another schema	Attribute of that type, and a directed association (`1`, `0..1` or `*`)
Required property	Tagged value `required = true` on the attribute
Tag	Interface with the stereotype «api», e.g. `PetsApi` for the tag `pets`
Operation (`GET /pets/{petId}`)	Operation of that interface, with its Method and Path set (see Endpoints: Method and Path)

Types

integer is int (long with int64); number is double; boolean is bool.
Strings with the formats date-time, date and uuid are DateTime, Date and Guid.
Arrays are List<T> (Set<T> with uniqueItems); maps are Map<string, T>.

Endpoints: Method and Path

In OpenAPI, an endpoint is an HTTP method on a URL path, such as GET /orders/{id}. In the diagram, an endpoint is an operation of an interface that has a Method and a Path. You set both in the element editor, next to the operation's name, parameters and return type.

Set them in the element editor

Add an interface for a group of endpoints, e.g. OrdersApi, and give it the stereotype api.
Select it and choose Edit → Edit Element… (or press Enter, or right-click it and choose Edit…).
Under Operations, add one operation per endpoint and fill in its Name, Parameters and Return type.
Pick its Method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS or TRACE. Leave it empty for an operation that is not an endpoint.
Type its Path, e.g. /orders/{id}. Put the names of path parameters in braces.

After OK, the diagram shows the endpoint in small type before the operation: «GET /orders/{id}» +getOrder(id: string): Order. An operation with a Method but no Path shows only the method: «GET».

What each part becomes in OpenAPI

In the element editor	In the exported OpenAPI description
Method and Path	The operation, under `paths` → the path → the method in lower case: `/orders/{id}:` → `get:`
Name	`operationId`
The interface, e.g. `OrdersApi`	The operation's tag: the interface's name without `Api`, e.g. `Orders`. An interface made by an import keeps its tag.
A parameter named in braces in the path (`id` in `/orders/{id}`)	A required path parameter
The parameter named `body` or `requestBody`; otherwise the first parameter whose type is a class of the diagram and that is not in the path	The request body, as JSON (`application/json`)
Any other parameter	A query parameter
Return type	The `200` response, with that type as its JSON schema. With no return type, or `void`: a `204 No Content` response.

Example

An interface OrdersApi with the stereotype api, and these operations:

Name	Parameters	Return type	Method	Path
`listOrders`	`status: OrderStatus`	`List<Order>`	`GET`	`/orders`
`createOrder`	`order: Order`	`Order`	`POST`	`/orders`
`getOrder`	`id: string`	`Order`	`GET`	`/orders/{id}`

They are exported as three endpoints. status is a query parameter, order is the request body (its type is a class of the diagram), and id is a path parameter:

paths:
  /orders:
    get:
      tags:
        - Orders
      operationId: listOrders
      parameters:
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/OrderStatus'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
    post:
      tags:
        - Orders
      operationId: createOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
        required: true
      responses:
        "200": …
  /orders/{id}:
    get:
      tags:
        - Orders
      operationId: getOrder
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200": …

Rules to know

Only interfaces hold endpoints. An interface with the stereotype api, or with at least one operation that has a Method, is an API: its operations are endpoints and it is not written as a schema. A Method and Path on an operation of a class are shown in the diagram, but not exported.
Every operation of an API interface needs both. One without a Method or a Path is left out, with a note: OrdersApi.helper has no HTTP method and path; it is not written as an endpoint.
The path starts with /. It is added when you leave it out: orders is written as /orders.
A method and path can be used once. A second operation with the same Method and Path is left out, with a note.
Every name in braces needs a parameter of that name. A name without one is still written, as a string path parameter, with a note: DELETE /orders/{orderId}: {orderId} is not a parameter of cancelOrder; it is written as a string path parameter. Rename the parameter or the name in braces so that they match.

The notes are listed in the message shown when the export is done.

When you import

An import fills in the Method and Path for you: each operation of the OpenAPI description becomes an operation of the «api» interface of its tag (or of its first path segment when it has none), with the method in upper case (GET) and the path as written. Change them in the element editor to move or rename an endpoint: the next export writes the endpoint where the diagram says it is.

Round trips: what UML has no place for (servers, security, descriptions, examples, other responses, …) is kept in tagged values named openapi.… and written back on export. When you change the diagram, the diagram wins.