JarCastingOpenApi 3 Plugin
openapi-jaxb plugin and demo application
1. Maven central
This project is available in maven central as:
<dependency>
<groupId>hu.icellmobilsoft.jaxb</groupId>
<artifactId>openapi-jaxb</artifactId>
<version>1.1.0</version>
</dependency>
2. openapi-jaxb plugin
An extension to the swagger-jaxb XJC plugin. When generating java code from xsd, this plugin annotates the generated classes with the proper OpenAPI and/or Swagger annotations (depending on the provided argument).
3. Swagger generation
It uses a fork of the be.redlab.jaxb:swagger-jaxb xjc plugin. The used fork extends the original plugin with the processing of the <xs:documentation> tags. The fork had been refactored (hu.icellmobilsoft.jaxb:swagger-jaxb) in order to simplify porting from Swagger to OpenAPI.
The original Swagger compatible genearation is still available with providing the -swaggerify argument, see: https://github.com/redlab/swagger-jaxb/blob/master/README.md
4. OpenAPI generation
4.1. Usage
The plugin is activated with the -openapify argument.
4.1.1. Use with org.jvnet.jaxb2.maven2:maven-jaxb2-plugin maven plugin
...
<plugin>
<groupId>org.jvnet.jaxb2.maven2</groupId>
<artifactId>maven-jaxb2-plugin</artifactId>
<version>0.13.3</version>
...
<configuration>
<schemaDirectory>src/main/resources</schemaDirectory>
<schemaIncludes>
<include>xsd/hu/icellmobilsoft/icon/dto/super.xsd</include>
</schemaIncludes>
<generateDirectory>${project.build.directory}/generated-sources/src/main/java</generateDirectory>
<args>
<arguments>-openapify</arguments> // (1)
</args>
<plugins>
<plugin> // (2)
<groupId>hu.icellmobilsoft.jaxb</groupId>
<artifactId>openapi-jaxb</artifactId>
<version>1.1.0</version>
</plugin>
</plugins>
<!--<dependencies>--> // (3)
<!--<dependency>-->
<!--<groupId>org.eclipse.microprofile.openapi</groupId>-->
<!--<artifactId>microprofile-openapi-api</artifactId>-->
<!--<version>1.0.1</version>-->
<!--</dependency>-->
<!--<dependency>-->
<!--<groupId>com.sun.xml.bind</groupId>-->
<!--<artifactId>jaxb-core</artifactId>-->
<!--<version>2.2.11</version>-->
<!--</dependency>-->
<!--</dependencies>-->
</configuration>
</plugin>
-
activate the plugin with adding
<arguments>-openapify</arguments>to//plugin/configuration/args. -
include the artifact
hu.icellmobilsoft.jaxb:openapi-jaxbunder//plugin/configuration/plugins. -
The original plugin README states that the transitive dependencies should be provided here, however it work without it..
|
Note
|
The -swaggerify argument is still available, both arguments can be provided, in that case the generated classes will be annotated with both OpenApi and Swagger related annotations. |
|
Important
|
In order to compile the generated sources the org.eclipse.microprofile.openapi:microprofile-openapi-api artifact should be included as dependency (at least with provided scope)! (This artifact contains the OpenApi annotations) |
<project ...>
...
<dependencies>
...
<dependency>
<groupId>org.eclipse.microprofile.openapi</groupId>
<artifactId>microprofile-openapi-api</artifactId>
<version>1.0.1</version>
<scope>provided</scope>
</dependency>
4.2. Details
It annotates the classes generated from XSD-s with the org.eclipse.microprofile.openapi.annotations.media.Schema annotation.
4.2.1. XSD Mapping
| XSD | Schema |
|---|---|
|
|
|
Class level |
|
Field level |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
4.2.2. Verbose description
Some xsd restrictions can not be included into OpenAPI schema definitions, and some OpenAPI implementations doesn’t process the Schema.enumeration-s properly (or other parameters), furthermore the <xsd:documentation>-s provided on the enumeration constants are not generated into the openAPI yaml. Because of these the plugin can be run with the verboseDescriptions flag in order to extended the description property with a list of restriction or for enums with the list of possible values and their respective documentation (if any).
Setting verbose description with maven-jaxb2-plugin maven plugin
...
<plugin>
<groupId>org.jvnet.jaxb2.maven2</groupId>
<artifactId>maven-jaxb2-plugin</artifactId>
<version>0.13.3</version>
...
<configuration>
<schemaDirectory>src/main/resources</schemaDirectory>
<schemaIncludes>
<include>xsd/hu/icellmobilsoft/icon/dto/super.xsd</include>
</schemaIncludes>
<generateDirectory>${project.build.directory}/generated-sources/src/main/java</generateDirectory>
<args>
<arguments>-openapify</arguments> // (1)
<arguments>-openapify:verboseDescriptions</arguments> // (2)
</args>
<plugins>
<plugin>
<groupId>hu.icellmobilsoft.jaxb</groupId>
<artifactId>openapi-jaxb</artifactId>
<version>1.1.0</version>
</plugin>
</plugins>
</configuration>
</plugin>
-
activate the plugin with adding
<arguments>-openapify</arguments>to//plugin/configuration/args. -
activate verboseDescription with adding
<arguments>-openapify:verboseDescriptions</arguments>to//plugin/configuration/args.
Examples
enumeration
<xs:simpleType name="OperationType">
<xs:annotation>
<xs:documentation xml:lang="en">Operation type</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:enumeration value="CREATE">
<xs:annotation>
<xs:documentation xml:lang="en">Creation exchange</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="MODIFY">
<xs:annotation>
<xs:documentation xml:lang="en">Modification exchange</xs:documentation>
</xs:annotation>
</xs:enumeration>
</xs:restriction>
</xs:simpleType>
Operation type
Restrictions:
* Enum:
* **CREATE** - Creation exchange
* **MODIFY** - Modification exchange
Operation type
Restrictions:
-
Enum:
-
CREATE - Creation exchange
-
MODIFY - Modification exchange
-
restricted type
<xsd:simpleType name="DateType">
<xsd:restriction base="xsd:date">
<xsd:minInclusive value="2010-01-01"/>
<xsd:pattern value="\d{4}-\d{2}-\d{2}"/>
</xsd:restriction>
</xsd:simpleType>
DateType
Restrictions:
* minimum: 2010-01-01
* exclusiveMinimum: false
* pattern: \d{4}-\d{2}-\d{2}
DateType
Restrictions:
-
minimum: 2010-01-01
-
exclusiveMinimum: false
-
pattern: \d{4}-\d{2}-\d{2}
4.2.3. Issues
Known limitations:
-
When multiple
documentationis defined under//annotation(ie. multi-language documentation), then only the last one will be processed.ie. from the following xsd only the
textwill be displayed as description<xs:annotation> <xs:documentation xml:lang="hu">szöveg</xs:documentation> <xs:documentation xml:lang="en">text</xs:documentation> </xs:annotation>
4.3. Example
Poc application: openapi-demo
5. OpenApi POC
POC application for openApi plugin
5.1. Modules
5.2. OpenApi Demo DTO
DTO module for openApi demo. A sample xsd is used to define the business objects, XJC is used with the openapi-jaxb plugin to process the xsd and generate the java representations annotated with OpenAPI annotations.
5.3. OpenApi Demo service
REST endpoint (/sample/xsd) which consumes and provides the SampleType object generated by xjc from the definition provided in the sample.xsd (in dto module).
Since io.thorntail:microprofile-openapi is bundled, the OpenAPI 3 yaml is available under /openapi.
6. Running the POC
-
[openapi-demo]$ mvn clean install -
[openapi-demo]$ java -jar openapi-demo-service/target/openapi-demo-service-1.1.1-SNAPSHOT-thorntail.jar
After startup the OpenApi yaml is available under localhost:8080/openapi.
