A consortium of major actors in the API market has launched the OpenAPI Initiative with the goal of standardizing the way to describe REST APIs. In short, OpenAPI is the standardized version of Swagger.
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.
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 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.
The next figure shows an overview of its main components: (1) OpenAPI Importer, (2) OpenAPI Modeler and (3) OpenAPI Generator;
The OpenAPI Importer 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 tool repository.
The OpenAPI Modeler provides a modeling editor for OpenAPI definitions based on UML and the OpenAPI UML profile. The editor is based on the open-source Papyrus modeling environment.
The OpenAPI Generator 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.
WAPIml is available as a set of plugins for Eclipse 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 UML2 plugin (i.e., tree-based format plus properties view) and Papyrus 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.
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 the Petstore OpenAPI definition. 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.
Finally, the tool will display the generated class diagram (see the example screenshot from the Petstore OpenAPI definition) 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 Properties view (e.g., see the lower part of the screenshot showing the stereotype APIOperation of the findPetsByStatus operation).
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 GitHub repository of WAPIml for more details about the tool support.