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.
To be able to generate an Open API specification based on your UML model the following steps need to be done:
Define an Open API Specification component with stereotype
«OpenAPI3Specification»Define one or more Open API Server that hosting your rest services
Mark the classes that should be published as Open API data types
Link your Open API Specification the 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.
Please also refer to: