From OpenAPI to UML (and back)
Tags: uml, openapi, api, swagger
Published: 2019-10-28 18:42:45

A consortium of major actors in the API market has launched the [OpenAPI Initiative](https://www.openapis.org/) with the goal of standardizing the way to describe REST APIs. In short, OpenAPI is the standardized version of [Swagger](https://swagger.io/).

OpenAPI is going to be a major player in the Web API ecosystem. But despite its importance, we don't have good ways to visualize OpenAPI definition files. Even less, to modify them on a graphical view and save the modified version back to a standard OpenAPI file. Especially using standard formats that facilitate the integration and manipulation of these OpenAPI models in other tools.  

To help with this, I'd like to introduce you [WAPIml](https://github.com/opendata-for-all/wapiml), part of our [Open Data for All project](https://github.com/opendata-for-all). 

WAPIml is a round-trip tool that leverages modeling techniques to create, visualize, manage, and generate OpenAPI definitions. WAPIml is implemented as an Eclipse-based editor for OpenAPI. It includes both an OpenAPI metamodel and a UML-based version of such metamodel, in the form of a UML profile. The choice of [UML](https://modeling-languages.com/uml-tools/) as a graphical notation to visualize OpenAPIs was an obvious choice given its dominance among the modeling languages. Profiles are the standard mechanism provided by UML to adapt the language to specific domains. 

## Architecture
The next figure shows an overview of its main components: (1) OpenAPI Importer, (2) OpenAPI Modeler and (3) OpenAPI Generator;

<img class="aligncenter wp-image-7195 size-large" src="https://modeling-languages.com/wp-content/uploads/2019/09/wapiml-cropped-1024x391.png" alt="WAPIml Tool architecture - From web APIs to UML and back" width="1024" height="391" />

The <strong>OpenAPI Importer</strong> is in charge of generating a UML class diagram annotated with OpenAPI stereotypes from an OpenAPI definition. This transformation iterates over the operations and definitions of the OpenAPI in order to generate classes, properties, operations, data types, enumeration, and parameters, accordingly. These elements are enriched with OpenAPI stereotypes to complete their definitions. This process relies on a set of heuristics to identify the most adequate UML class to attach each OpenAPI operation to. The full list of heuristics can be found in the <a href="https://github.com/opendata-for-all/WAPIml/#notes" target="_blank" rel="noopener noreferrer">tool repository</a>.

The <strong>OpenAPI Modeler</strong> provides a modeling editor for OpenAPI definitions based on UML and the OpenAPI UML profile. The editor is based on the open-source [Papyrus](https://www.eclipse.org/papyrus/) modeling environment.

The <strong>OpenAPI Generator</strong> is in charge of generating an OpenAPI definition from a UML class diagram annotated with the OpenAPI UML profile. It applies a process similar to the importer but in the reverse order. 

Read more technical details on all these transformations [here](https://modeling-languages.com/wapiml-web-api-uml/).

## Using WAPIml

WAPIml is available as <a href="https://github.com/opendata-for-all/wapiml" target="_blank" rel="noopener noreferrer">a set of plugins for Eclipse</a> extending the UI of the platform to provide: (i) a wizard to drive the generation of a UML model from an OpenAPI definition (either in JSON or YAML); (ii) an editor for these models provided as an extension to <a href="https://www.eclipse.org/modeling/mdt/?project=uml2#uml2" target="_blank" rel="noopener noreferrer">UML2 plugin</a> (i.e., tree-based format plus properties view) and <a href="https://www.eclipse.org/papyrus/" target="_blank" rel="noopener noreferrer">Papyrus</a> modeling environment (i.e., diagram-based format plus rich properties view); and (iii) a contextual menu to generate an OpenAPI definition in JSON or YAML from a UML model annotated with OpenAPI UML profile.

The first step in the importation wizard allows the user to choose whether he/she wants to apply the OpenAPI profile and discover associations, as shown below.

<img class="aligncenter" src="https://camo.githubusercontent.com/add90c63b19ba73ea112779e2c7929f5270403cb/68747470733a2f2f6f70656e646174612d666f722d616c6c2e6769746875622e696f2f776170696d6c2f696d616765732f776170696d6c2f70616765312e504e47" />

Next, the wizard displays the inferred associations which are: (i) explicitly defined in the OpenAPI file or (ii) discovered by analyzing the schema properties to find matches which other schemas. The second kind of associations is only provided when the flag "Discover associations" is checked on the first page. The screenshot below provides an example of such page for <a href="https://petstore.swagger.io/v2/swagger.json" target="_blank" rel="noopener noreferrer">the <em>Petstore</em> OpenAPI definition</a>. Note that, this page allows the user to cure these associations (e.g., edit the aggregation kind, delete an association). The final UML model is generated by clicking on the "Finish" button.
<img class="aligncenter" src="https://camo.githubusercontent.com/9f60db52575cfd8f6d700dfadea72e19fea1b3cc/68747470733a2f2f6f70656e646174612d666f722d616c6c2e6769746875622e696f2f776170696d6c2f696d616765732f776170696d6c2f70616765322e504e47" alt="page1" />

Finally, the tool will display the generated class diagram (see the example screenshot from <a href="https://petstore.swagger.io/v2/swagger.json" target="_blank" rel="noopener noreferrer">the <em>Petstore</em> OpenAPI definition</a>) using Papyrus. 

As can be seen, the Pet class, which represents a pet definition, is annotated with the stereotype schema, while its extracted attributes are annotated with APIProperty, and its extracted operations are annotated with APIOperation and Security. The tag values complementing the applied stereotypes can be showed using comments (e.g., see the Schema comment box next to the class Pet) and modified using the <em>Properties</em> view (e.g., see the lower part of the screenshot showing the stereotype APIOperation of the findPetsByStatus operation).

<img class="aligncenter size-large wp-image-7193" src="https://modeling-languages.com/wp-content/uploads/2019/09/wapiml-model-1-1024x555.png" alt="WAPIml editor" width="1024" height="555" />

Users can then rely on this editor to modify the OpenAPI definition. Once you're done, the tool integrates also a contextual menu to generate back the OpenAPI file either in JSON or YAML format from this model. 

Check the <a href="https://github.com/opendata-for-all">GitHub repository</a> of WAPIml for more details about the tool support.