...
When you want to publish your REST Services 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 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 REST services
Mark the classes that should be published as Open API data types
Link your Open API Specification the with the packages that contain your data type definitions
Link your Open API Specification with the REST Services 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 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.
Final 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 serviceservices.
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 specification specifications into smaller independent pieces.
...
Open API does not define an explicit concept of modules or anything like that but it allows to reference on 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 directly 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:
...