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.
To help with this, I'd like to introduce you WAPIml, part of our Open Data for All project.
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.
Architecture
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.
Using WAPIml
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.
Top comments (5)
Very interesting, both the general technique of transforming back and forth between software development artifacts and models, and it's integration into Eclipse. Thanks for sharing both the concepts and code!
Would it make sense to target Ecore in addition to UML2? I know many tools can use both Ecore and UML2 as input, but it may be different when used as a target of a transformation. Still, you can think of them as two different backends to a generic transformation (particular since both ecore and UML2 is implemented in ecore).
Another idea is to explore a custom notation using Sirius, rather than using class diagrams. That could be more usable for some developers. (I'm not sure how flexible papyrus is in this respect.)
Yes. Ecore could be an easy target as well. We chose UML because it's more well-known (outside the "core" modeling community) but I agree that for people that may want to build their own tools/extensions on top of WAPIml, an Ecore output would make sense.
About the custom notation, we see it as a different path with its own pros and cons (kind of the always on-going discussion about DSLs vs UML).
To add to what Jordi said, I want to mention that we do have an OpenAPI metamodel implemented in Ecore which we use in an intermediate step between JSON/YAML and UML (we first generate an OpenAPI model instance then we transform it to a UML model). This metamodel could be used for instance to create a custom notation with Sirius or to perform transformations.
After submitting my comment I checked out your repo and found the metamodel!
Yes, that can be a good starting point for other tools, e.g. a custom notation using Sirius. Since I'm maintaining the PlantUML integration in Eclipse, it's also relevant to use the textual PlantUML notation as another backend of the transformation from the metamodel to class diagram, possibly going through an Ecore model.
We use PlantUML to render models created with our Slack Modeling Bot, but there we just do a direct transformation from the UML Ecore model to PlantUML syntax. But good to now your extension exists!