(you can now read about WAPIml, the successor of the OpenAPI to UML, described here https://modeling-languages.com/wapiml-web-api-uml/)
REpresentational State Transfer (REST) has become the prominent architectural style for designing Web APIs. This increasing adoption has triggered the creation of languages to formally describe REST APIs, thus facilitating and promoting their usage. In particular, a consortium of companies has created the OpenAPI Initiative, which aims at creating a vendor-neutral, portable, standard and open specification for describing REST APIs. OpenAPI specification has become the choice of reference for describing REST APIs, and its adopters can benefit from a plethora of tools for documenting, developing and integrating REST APIs. However, current documentation tools for OpenAPI only describe REST APIs in HTML pages using text and code samples, thus requiring a considerable effort to visualize and understand what the APIs offer.
In this post, we present a tool called OpenAPItoUML, which generates UML models from OpenAPI definitions, thus offering a better visualization of the data model and operations of REST APIs. OpenAPItoUML is available as an open source Eclipse plugin. All the instructions on how to install and use the tool are available in the Github repository.
This work is going to be presented at ICWE’18 (18th International Conference on Web Engineering). Come to see OpenAPItoUML live if you’re around or check the content of the paper below (you can also download the paper on PDF).
The REpresentational State Transfer (REST) is an architectural style which allows relying on URIs and HTTP messages to build interoperable Web applications. Due to its lightweight nature, adaptability to the Web, and scaling capacity, REST has become the preferred style for building Web APIs. For instance, reports from ProgrammableWeb, the biggest repository of public Web APIs with more than 19,000 APIs, show that more than 80% of the registered APIs are REST.
The growing importance of REST APIs has been supported by the proposal of several languages aimed at formally describing REST APIs and therefore facilitating their discovery and integration (e.g., Swagger, API Blueprint, and RAML). Recently, and aiming at standardizing the way to describe REST APIs, several vendors have announced the OpenAPI Initiative (OAI). OAI has succeeded in attracting major companies (e.g., Google, Microsoft or IBM) and has created the OpenAPI specification (initially based on Swagger), which has become the choice of reference to describe REST APIs. For instance, APIs.guru, a repository of OpenAPI definitions, lists more than 800 APIs.
There is therefore a need for creating an ecosystem of supporting tools to facilitate the integration, development, and documentation of REST APIs described by OpenAPI (e.g., generating client SDKs, documentation pages or server skeleton). In this paper we propose a tool, called OpenAPItoUML, which contributes to this ecosystem by allowing the visualization of OpenAPI definitions as UML Class diagrams (including both the structure and behavior of the API), thus offering a better visualization of the capabilities of REST APIs. To the best of our knowledge, current documentation tools for OpenAPI (e.g., ReDoc and Swagger UI) display the operations and data structures of the definitions in HTML pages using only text and code samples, which complicate the understanding and visualization of REST APIs. Only JSONDiscoverer  allows visualizing the data schema of JSON-based REST APIs but focus on the inputs/outputs of the operations and does not model the operations themselves nor supports OpenAPI descriptions.
The rest of the paper is organized as follows. Section 2 describes our approach and Section 3 presents the tool. Section 4 concludes the paper and presents the future work.
2 The OpenAPI to UML Approach
We propose a model-based approach to visualize OpenAPI definitions as UML Class diagrams. From an input OpenAPI definition, our approach extracts first an OpenAPI model which is then transformed into a UML model (i.e., Class diagram) showing the data structure and operation signatures of the API. While the intermediate OpenAPI model is useful to perform other kinds of advanced analysis on
the OpenAPI definition, it is more convenient to generate a UML model for visualization and comprehension purposes. Being a standard UML model, our result can be automatically rendered and modified using any of the plethora of UML modeling tools (e.g., Papyrus or UML designer).
The OpenAPItoUML process is depicted in Figure 1. As can be seen, the process takes as input an OpenAPI definition, which can be (1) provided by the API provider; (2) generated by tools such as APIDiscoverer , which allows discovering OpenAPI definitions from API call examples; or (3) derived from other API definition formats (e.g., API Blueprint, RAML) using tools such as API Transformer, which allows converting API definitions.
The OpenAPItoUML process generates UML models in three steps (see the steps 1, 2, and 3 in Figure 1), which we will illustrate with the Petstore API example, a REST API for a pet store management system, released by the OpenAPI community as a reference. Figure 2.1 shows an excerpt of the Petstore OpenAPI definition including the operation findPetsByStatus and the schema definition Pet.
The first step (see step 1 in Figure 1) extracts a model conforming to our OpenAPI metamodel from the input OpenAPI definition. More details about this metamodel can be found in our previous work . Since the OpenAPI metamodel conforms to the OpenAPI specification, the generation of OpenAPI models from OpenAPI definitions is almost straightforward and only special attention had to be paid to deal with JSON references. We omitted to show this model for the Petstore example as it mirrors the OpenAPI definition shown in Figure 2.1.
The second step (see step 2 in Figure 1) performs a model-to-model transformation to generate a model conforming to the UML metamodel from the previously extracted OpenAPI model. This transformation iterates over the operations and definitions of the OpenAPI model in order to generate classes, properties, operations, data types, enumeration, and parameters, accordingly. This process relies on a set of heuristics to identify the most adequate UML class to attach each OpenAPI operation to. Heuristics are based on the analysis of the tags, parameters and responses of the operation1. The full list of heuristics can be found in the tool website . Figure 2.2 shows an excerpt of generated UML model for the Petstore API. As can be seen, the OpenAPI schema Pet is transformed to the UML class Pet, while the OpenAPI operation findPetsByStatus is transformed into the UML operation findPetsByStatus in the Pet class.
The last step of the process (see step 3 in Figure 1) serializes the generated UML model as an XMI file (standard XML format for UML tool interoperability). Users can rely on tools such as Papyrus and UML designer to open and visualize such file.
3 Our OpenAPItoUML plugin
OpenAPItoUML has been implemented in Java as a plugin for the Eclipse platform . The plugin extends the platform to provide a contextual menu to obtain a UML model from an OpenAPI definition (using its JSON representation format). Figure 3 shows a screenshot of our plugin including the created contextual menu (on the left side) and the generated Class diagram for the Petstore API displayed using Papyrus (on the right side), the “de facto” UML tool for Eclipse. The OpenAPI metamodel has been implemented using the Eclipse Modeling Framework (EMF), while UML models rely on UML2, an EMF-based implementation of the UML 2.5 OMG metamodel.
We have presented OpenAPItoUML, a tool to generate UML models from OpenAPI definitions. We believe our approach contributes to the ecosystem of tools for OpenAPI by offering developers the opportunity to understand and easily visualize the capabilities of REST APIs. OpenAPItoUML is available as an Open Source Eclipse plugin . The plugin repository includes a Get started guide which explains the steps to install the plugin and generate and visualize UML models.
 OpenAPItoUML https://github.com/SOM-Research/openapi-to-uml
 Cánovas Izquierdo, J., Cabot, J.: JSONDiscoverer: Visualizing the schema lurking behind JSON documents. Knowl.-Based Syst. 103, 52–55 (2016)
 Ed-Douibi, H., Cánovas Izquierdo, J., Cabot, J.: Example-driven Web API Specification Discovery. In: Eur. Conf. on Modelling Foundations and Applications (2017)
1 When no class is a good fit for the operation, an artificial class is created to host the operation.
My name is Hamza Ed-Douibi. I am a postdoctoral fellow working in the SOM Research Lab at the Internet Interdisciplinary Institute (IN3) of the Open University of Catalonia (UOC) in Barcelona.
Do you also have (or know of) a capability to generate OpenAPI specifications from UML models (done in an appropriate style)? This would give the full ability to reverse engineer an API into UML, update the model and regenerate the API.
Plus, I happen to have an interest right now in generating OpenAPI specs from UML. 🙂
Not right now but with our current infrastructure (e.g. the OpenAPI metamodel) this shouldn’t be difficult, even if, as you say, there are some special cases to be taken into account like the treatment of inheritance relationships
Hi Ed, the new tool (successor of this one) includes also the UML to OpenAPI generation part. Available here: https://modeling-languages.com/wapiml-web-api-uml/
Does this support yaml based OpenAPI specs as well? or is it JSON only?
For now only JSON is supported. We don’t think this to be a limitation since there are many tools that transform YAML to JSON and vice versa (e.g., https://editor.swagger.io/).
Most interesting! However, looks like the update site link is down: https://som-research.github.io/openapi-to-uml/update/
And a question – in what ways is this related to the work of Prof. Canovas of your lab on JSON Schema to UML conversion? https://github.com/SOM-Research/jsonSchema-to-uml
The update site is not down. It’s normal to hit a 404 page in the browser since the URL is intended to work in Eclipse. Follow the instructions in the README page to install the tool.
OpenAPItoUML generates UML models from OpenAPI definitions, while JSONSchematoUML generates UML models from JSON schemas. Both take a JSON file as input but one holds the definition of a Web API following OpenAPI specification, while the other holds the definition of a JSON schema.
Thanks for the response, Hamza! I did try from within Eclipse, but that fails with “javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.” I suspect this could be due to the fact that I’m behind a firewall and there is an SSL intercepting proxy.
Is there a way I can download the plugin (as a tgz maybe) and just unzip it to my Eclipse dropins directory?
I just checked the update site and it works fine. I think the issue comes from your proxy as you suggested. As a workaround to install the tool, go to the branch gh-pages in the GitHub repository. Click on Clone or download -> Download ZIP then copy the two JAR files located in the folder update into your dropins folder. You need to do the same with the plugin OpenAPI-metamodel (using the same instructions) since the tool depends on it.
I hope this helps.
I am evaluating a toolchain to generate code from OpenAPI documents (YAML but perhaps JSON). The toolchain needs to be completely automated from OpenAPI to source code to include in a build system. We generate C++98, C++11+, CSharp, and Typecript code. I an considering using OpenAPItoUML to generate UML2, and using Acceleo for the final code generation. There is documentation supporting how to use Acceleo standalone to generate code. Is there an equivilent way to use OpenAPItoUML standalone? Thanks!
The core project (edu.uoc.som.openapitouml) does not depend on Eclipse UI and in theory can be used in a standalone mode. However, some adjustments might be needed to change URIs loading (platform is not available in standalone mode) and import all the dependencies. I’ll add an issue in the GitHub repo of the tool to ask for documentation to support that. Since you’re interested in code generation, you may also consider our OpenAPI metamodel which is implemented using EMF. It also includes an importer to generate instances of the metamodel from JSON files (it can be used in a standalone mode).
I am looking for your input to create OpenAPI specification from UML defined in Enterprise Architect
A UML model alone could not be used to generate an OpenAPI definition. You may definite some heuristics to generate missing parts (e.g., a path per class, generic status codes) but this will not be enough. We are working on an extension of OpenAPItoUML in which we included a UML profile to extends UML vocabulary in order to add support for OpenAPI specification. We rely on the UML model and information coming from the profile to generate OpenAPI definitions. The new version of the tool will be available in the few coming weeks. Our tool is based on Eclipse but there are many tools which allow you to transform UML models defined using Enterprise Architect to Eclipse based UML models.
Hi. You can use a free online tool to convert YAML to JSON https://freetools.site/data-converters/yaml-to-json