How to publish REST Services as
...
OpenAPI 3 specification
When you want to publish your REST Services services also using Open API OpenAPI 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 OpenAPI 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 OpenAPI Specification component with stereotype
«OpenAPI3Specification»Define one or more Open API OpenAPI Server that are hosting your rest REST services
Mark the classes that should be published as Open API OpenAPI data types
Link your Open API OpenAPI Specification the with the packages that contain your data type definitions
Link your Open API OpenAPI 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 OpenAPI 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 OpenAPI Specification. To generate a valid Open API OpenAPI 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 «OpenAPI 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 OpenAPI specification.
When generating code for OpenAPI types JEAF Generator will also respect information about access type of properties (read-only, read-write and write-only). They can either be defined for OpenAPI only using stereotype «OpenAPI Property» or through UML standard fields (readOnly in UML) or through Java Validation annotations (Java Bean Validation Stereotypes).
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.
Final To define which data type definitions belong to your OpenAPI 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 OpenAPI Specification and your REST serviceservices.
How to modularize
...
OpenAPI Specifications
As soon as you will start to work with Open API OpenAPI 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 OpenAPI 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 OpenAPI Specification. And this is exactly the way how we can modularize our specs. Instead of defining one large Open API OpenAPI 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 OpenAPI 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 «OpenAPI Spec Reference»).
When you define dependencies between Open API OpenAPI 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:
...