openapi-jaxb plugin

1. Maven central

This plugin is available in maven central as:

    <dependency>
        <groupId>hu.icellmobilsoft.jaxb</groupId>
        <artifactId>openapi-jaxb-plugin</artifactId>
        <version>${version}</version>
    </dependency>

2. openapi-jaxb plugin

Openapi XJC plugin. When generating java code from xsd, this plugin annotates the generated classes with the proper OpenAPI annotations.

2.1. Compatibility

Plugin version JAXB version Microprofile OpenAPI version

1.x

2.0

1.0+

2.0.x

4.0

3.0+

2.1.x

4.0

3.1+

3. OpenAPI generation

3.1. Usage

The plugin is activated with the -openapify argument.

3.1.1. Use with maven plugin

The plugin requires XJC from jaxb 4.0, a viable solution is using the phax/maven-jaxb2-plugin jaxb 4.0 maven plugin fork.

<!-- ... -->
<plugin>
    <groupId>com.helger.maven</groupId>
    <artifactId>jaxb40-maven-plugin</artifactId>
    <version>0.16.0</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-plugin</artifactId>
				<version>${openapi-jaxb-plugin.version}</version>
            </plugin>
        </plugins>
    </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.

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) 
	<!-- ... -->
	<dependencies>
			<!-- ... -->
			<dependency>
				<groupId>org.eclipse.microprofile.openapi</groupId>
				<artifactId>microprofile-openapi-api</artifactId>
				<version>${microprofile-openapi-api.version}</version>
				<scope>provided</scope>
			</dependency>
            <!-- ... -->
	</dependencies>

3.2. Details

It annotates the classes generated from XSD-s with the org.eclipse.microprofile.openapi.annotations.media.Schema annotation.

3.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]

3.2.2. Verbose descriptions

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 plugin
<!-- ... -->
<plugin>
    <groupId>com.helger.maven</groupId>
    <artifactId>jaxb40-maven-plugin</artifactId>
    <version>0.16.0</version>
    <!-- ... -->
    <configuration>
        <args>
			<arguments>-openapify</arguments><!--(1)-->
			<arguments>-openapify:verboseDescriptions</arguments><!--(2)-->
        </args>
        <plugins>
            <plugin>
				<groupId>hu.icellmobilsoft.jaxb</groupId>
				<artifactId>openapi-jaxb-plugin</artifactId>
				<version>${openapi-jaxb-plugin.version}</version>
            </plugin>
        </plugins>
    </configuration>
</plugin>

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

  2. activate verboseDescription with adding <arguments>-openapify:verboseDescriptions</arguments> to //plugin/configuration/args.

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

Restrictions:
* Enum:
  * **CREATE** - Creation exchange
  * **MODIFY** - Modification exchange
Rendered

Operation type

Restrictions:

  • Enum:

    • CREATE - Creation exchange

    • MODIFY - Modification exchange

restricted type
xsd 
    <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>
Description 
DateType

Restrictions:
* minimum: 2010-01-01
* exclusiveMinimum: false
* pattern: \d{4}-\d{2}-\d{2}
Rendered

DateType

Restrictions:

  • minimum: 2010-01-01

  • exclusiveMinimum: false

  • pattern: \d{4}-\d{2}-\d{2}

3.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">text</xs:documentation>
    <xs:documentation xml:lang="en">text</xs:documentation>
</xs:annotation>

4. Migration guide

4.1. v1.x → v2.0.0

OpenAPI jaxb plugin 1.x → 2.0.0 migration guide.

4.1.1. Changes

Maven structure

In version 1.0 the repository consisted of 2 maven projects

  • openapi-demo

    • demo project for plugin

    • maven coordinates - hu.icellmobilsoft.jaxb:openapi-demo

  • openapi-plugin

    • actual plugin

    • maven coordinates - hu.icellmobilsoft.jaxb:openapi-jaxb

Since openapi-demo was not maintained, and depended on thorntail we decided to remove it entirely from 2.0. The demo xsd-s were moved into a test sub-module with actual tests written to see if the generated classes are annotated as expected.

As of 2.0 the new project structure is

  • openapi-jaxb - parent project, maven coordinates - hu.icellmobilsoft.jaxb:openapi-jaxb

    • openapi-jaxb-plugin - actual xjc openeapi generator plugin, maven coordinates - hu.icellmobilsoft.jaxb:openapi-jaxb-plugin

    • openapi-jaxb-test - testsuite for the plugin - hu.icellmobilsoft.jaxb:openapi-jaxb-test

migration

The plugin maven artifactId changed from openapi-jaxb to openapi-jaxb-plugin

Dependencies, prerequisites
Microprofile OpenAPI specification

MicroProfile OpenAPI Specification has been upgraded to version 3.0.

migration

The specification change does not include any breaking change in the plugin, it is most likely to work with previous mp-openapi versions, still 3.0 is recommended.

JAXB 2.0 → Jakarta XML Binding 4.0

JAXB 2.0 has been changed to Jakarta XML Binding 4.0, thus the plugin needs XJC from the 4.0 implementation.

migration

Compatible maven plugin for generation is com.helger.maven:jaxb40-maven-plugin:0.16.0, more info: Use with maven plugin

4.2. v2.0.0 → v2.1.0

OpenAPI jaxb plugin 2.0.0 → 2.1.0 migration guide.

4.2.1. Changes

Microprofile OpenAPI version

Microprofile OpenAPI has been updated from 3.0.0 to 3.1.0 (part of Microprofile 6.0)