How to publish REST Services as Open API 3 specification
When you want to publish your REST services also using Open API 3 specification standard then this can be done very simple. Only a small amount of additional information inside the UML model is required and then JEAF Generator can generate a complete Open API 3 specification of your services.
Therefore the following steps need to be done:
Define an Open API Specification component with stereotype
«OpenAPI3Specification»Define one or more Open API Server that are hosting your REST services
Mark the classes that should be published as Open API data types
Link your Open API Specification with the packages that contain your data type definitions
Link your Open API Specification with the REST services you want to publish
The example model above shows what needs to be done the publish your REST services as Open API Specification.
As you can see you need to create a component that is tagged with stereotype «OpenAPI3Specification». This component represents the YAML file that will be generated as Open API Specification. To generate a valid Open API Specification it is required that you provide some additional information. They can be defined using the tagged values of stereotype (for details please see page «Open API 3 Specification»).
If you like you can also define the servers on which your REST services are available. To do so you again need to create a new component in your UML model. This time it has to be tagged with stereotype «OpenAPIServer». In addition also a dependency between your specification component and your server has to be defined.
In most cases your REST service will not only work with simple types but will also make use of complex types which are already defined as classed in your model. In this case you need to mark your classes with stereotype «OpenAPIType» and that’s it. Most likely you will also have some enumerations. Here it’s the same. Mark them with stereotype «OpenAPIEnumeration» and they will also be part of your Open API specification.
As you can see in the diagram above also so called bean parameters are supported. Bean parameters can be used for REST services to group a set of parameters together e.g. you always have the same context parameters that are supported on requests.
To define which data type definitions belong to your Open API Specification you simply need to define a dependency to their packages. JEAF Generator will then add all of them to your specification.
The final step is to also connect your REST services with the specification. To do so you need to define a dependency between your Open API Specification and your REST services.
How to modularize Open API Specifications
As soon as you will start to work with Open API on a more complex scenario you will find out that the YAML files will become rather big and confusing. Of course you still have your UML model where you have a way better overview. However also from the life cycle perspective it might be a good idea to split a large specifications into smaller pieces.
Open API does not define an explicit concept of modules or anything like that but it allows to reference elements that are located in another Open API Specification. And this is exactly the way how we can modularize our specs. Instead of defining one large Open API Specification in the UML model we define multiple of them and them link them together using dependencies with stereotype «OpenAPISpecReference».
As you can see in the diagram above Open API Specification Product Services has a dependency on Product Base Definitions. This means that all types from Product Base Definitions can also be used in Product Services. By default it is assumed that the referenced specification is located in the same directory as the other one. However it it also supported to define an URL for the referenced specification (for details please refer to stereotype «Open API Spec Reference»).
When you define dependencies between Open API Specifications please ensure that all of them support Semantic Versioning otherwise changes of dependent specification might make your API incompatible to previous versions.
Please also refer to: