OpenApi 3 Plugin

Table of Contents

• 1. Maven central
• 2. openapi-jaxb plugin
• 3. Swagger generation
• 4. OpenAPI generation
  • 4.1. Usage
    • 4.1.1. Use with org.jvnet.jaxb2.maven2:maven-jaxb2-plugin maven plugin
  • 4.2. Details
    • 4.2.1. XSD Mapping
    • 4.2.2. Enum handing
    • 4.2.3. Issues
  • 4.3. Example
• 5. OpenApi POC
  • 5.1. Modules
  • 5.2. OpenApi Demo DTO
  • 5.3. OpenApi Demo service
• 6. Running the POC
• 7. Generated examples

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>

1. activate the plugin with adding <arguments>-openapify</arguments> to //plugin/configuration/args.

2. include the artifact hu.icellmobilsoft.jaxb:openapi-jaxb under //plugin/configuration/plugins.

3. 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
//annotation/documentation	Schema.description
//complexType/@name	Class level Schema.name
//element/@name	Field level Schema.name
//element/@maxOccurs	Schema.maxLength
//element/@minOccurs	Schema.minLength
//simpleType/restriction/minInclusive	Schema.minimum and Schema.exclusiveMinimum = false
//simpleType/restriction/minExclusive	Schema.minimum and Schema.exclusiveMinimum = true
//simpleType/restriction/maxInclusive	Schema.maximum and Schema.exclusiveMaximum = false
//simpleType/restriction/maxExclusive	Schema.maximum and Schema.exclusiveMaximum = true
//simpleType/restriction/minLength	Schema.minLength
//simpleType/restriction/maxLength	Schema.maxLength
//simpleType/restriction/length (Has a higher priority than maxLength,minLength)	Schema.maxLength and Schema.minLength
//simpleType/restriction/pattern	Schema.pattern
//simpleType/restriction[@base="xs:string"]/enumeration[n]/@value	Schema.enumeration[n]

4.2.2. Enum handing

Some openAPI implementations doesn’t process the Schema.enumeration-s properly, furthermore the <xsd:documentation>-s provided on the enumeration constants are not generated into the openAPI yaml. Because of these the description property is extended for enums with the list of possible values and their respective documentation (if any).

Example

xsd

<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>

Description

Operation type
* **CREATE** - Creation exchange
* **MODIFY** - Modification exchange

Rendered

Operation type

• CREATE - Creation exchange

• MODIFY - Modification exchange

4.2.3. Issues

Known limitations:

• When multiple documentation is defined under //annotation (ie. multi-language documentation), then only the last one will be processed.

  ie. from the following xsd only the text will 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.

openapi-demo/openapi-demo-dto/src/main/resources/xsd/hu/icellmobilsoft/jaxb/openapi/dto/sample.xsd

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

1. [openapi-demo]$ mvn clean install

2. [openapi-demo]$ java -jar openapi-demo-service/target/openapi-demo-service-1.0.0-SNAPSHOT-thorntail.jar

After startup the OpenApi yaml is available under localhost:8080/openapi.

7. Generated examples

• OpenAPI 3.0 YAML

• HTML generated from OpenAPI yaml with redoc