How to Automate the OpenAPI Specification Generation from a Visual Design UML Model
Introduction
In my previous post I’ve discussed how REST APIs can be designed using a visual modelling tool (Sparx Enterprise Architect) with standard UML concepts, such as interfaces and classes. In this post I’ll show how to generate an OpenAPI specification from the UML model.
Organizing the Architecture Repository
The OpenAPI specification is linear and it contains objects like Info, Tags, Servers, Paths, Components -> Schemas & Security Schemes and Security
Organizing the repository to match the OpenAPI specification makes the specification generator easier to implement. I’m organizing the design in two main packages, Paths and Resources. Resources map to components->schemas in the OpenAPI specification. Inside each package are sub-packages that correspond to individual domains implemented by stand-alone microservices, as illustrated in the picture below.
The organization of the repository is intentional, as it addresses two use cases. The most common one — a team generates the specification for their own domain, e.g. Party or Accounts. The other use case, the organization needs to publish a global OpenAPI specification, encompassing all microservices, to share with its clients for example. For this use case the top packages for paths and resources can be used.
Building the OpenAPI Specification Generator
Once the API design is completed, there are two options: a) generate the specification from the Sparx Repository (the *.eax or the newer *.qea format for EA 16.0 which is a SQL db) or b) export the model to XMI and use this file as the source for the generation. As the Sparx EA formats are proprietary, and may change over time, I chose to use the XMI file.
To design and build the OpenAPI Specification Generator, I used a streaming approach, adding specification elements to an output file in the order of appearance: info, tags, servers, paths, components, security. While the UML model is suitable to design paths and resources, capturing state in an UML model is more tedious, being done using tags on different elements of the model. As a trade-off analysis, one has to decide if the model should be ‘whole’ or if it is OK not to model the specification’s data elements, e.g. info, tags, servers, security. The second approach improves maintainability, as the data can be captured via configuration files or even the UI of the specification generator.
The design for the generator is shown in the diagram below. There is an orchestrating component, and components to generate info, tags, servers, paths, components and security. In order to avoid generating resources not used by paths, where will be a dynamically built set of the resources referenced by paths and the ones referred by other resources.
The XMI Specification
Next, let’s look at the structure of the XMI file for the API design described in the previous article. To save a model as XMI, in Sparx EA go to the ‘Publish’ tab -> Export XMI and choose version 2.1.
The organization of the XMI file follows that of the model shown in the navigator. In the Navigator pane we have Model->API Model ->Paths ->Accounts as packages, and then to stereotyped interfaces — Accounts and Account. The organization of the XMI is the same
Thus in order to generate the paths the API Specification generator has to parse the XML file, starting with the package that contains the paths we want to generate. In Sparx EA one can get the GUID for the package, which is the xmi:id field in the XML. The query parameters and the successful response (200 for GET, PUT, PATCH, DELETE or 201 for POST) can be defined in UML; however the error codes (the 400s and 500s) cannot be defined in the model and they are part of the generator. I prefer a cookie-cutter approach and define in advance the set of the return codes the HTTP methods return.
Here is a look at the property form, and where the GUID for an element in the navigator window can be found
Example of the OpenAPI Specification Generator
Instead of trying to explain the structure of the XMI file in detail, I am going to share a small set of Python scripts. They cover the basics of generation, and output a semantically correct specification that can be validated with the Swagger Editor.
The UI facilitates cut and paste for data entry:
The GUID input fields are the GUIDs for the top Paths and Resources GUIDs that can be found in the properties view of the package
How to use:
- Copy and paste the GUIDs for the top Paths and Resources packages and input them in the generator. Strip the curly brackets
- Select the xmi file from file system
- Decide where to save the output
- Set the title for the OpenAPI Specification
- Choose the security that the APIs will implement
The Sparx EA model, the xmi file and the Python scripts are in GitHub. The scripts can be evolved to handle edge use cases and additional data types.
