Introduction
Hello everybody and welcome to my very first post on dev.to :)
I have been almost here for one year now (joined: Feb 24, 2019, just checked it now :D)
I have been a developer since 2016 but I always liked computer and programming, so basically after my official job I come home and I work on side-project with friends or just for fun. My main interests are Java related topics, I like both Spring and Java EE world and I think #Hibernate is my favorite third party framework (kudos to the boys/girls at JBoss).
I live and work in Debrecen, in Hungary, this is the second largest city in the country and there are a lot of opportunities for developers, the university is here for the upcoming devs, but I prefer coding related schools with more practical stuff :)
What did I bring to you?
At my last job we were preferring XSD2Java class based DTO class generation with a lot of reasons and we were building microservice architecture based applications and we were providing functionalities for clients (both internal (internal applications) and external clients).
The documentation for these classes and API endpoints were mandatory and we were experimenting with Swagger, at this time we were a using Java EE related framework called Thorntail (a.k.a Wildfly Swarm), and it came really handy to just put some annotation on the classes and API endpoints to document them.
The problem was the following:
- All of our DTOs, which were part of the communication, were generated by the maven-jaxb2-plugin and we were not able to annotate our generated classes because on the next generation the whole stuff would go to the trash can (/dev/null).
Solution: JAXB2 plugin supports external dependencies to take part in the class generation and we found a few options to extend our class generation phase.
This Redlab Swagger JAXB Plugin helped us a lot but it just hepled us to annotate our fields with the proper Swagger annotations like @ApiModel and @ApiModelProperty, nothing special, if you take a closer look at these annotations you will see that there are a lot of configuration options like, the required, allowableValues, description attributes.
As I quited the company, they moved to the OpenAPI specification which is a way more rich specification, I stayed with Swagger at my side-projects and at my job.
There is no problem with Swagger, OpenAPI just got a few new ways to express schemas.
I started to look around the internet, GitHub and I found that there is a lot of fork of the mentioned JAXB Plugin, and there is one which is way more expressive than the original one.
Andreas-Maier-NTT
/
swagger-jaxb
JAXB XJC Plugin for automatically adding annotations from Swagger to generated classes from an XSD
swagger-jaxb
JAXB XJC Plugin for automatically adding annotations from Swagger to generated classes from an XSD
Tests run in separate project, see here for the code https://github.com/redlab/swagger-jaxb-tck
Usage
- REQUIRE Java 8 or higher!
- build the plugin with maven
- install it in your local repo
- add the plugin to your classpath and use -swaggify on your jaxb command line or configure it i your pom or
- add sonatype snapshot repository to your repo manager. ( post an issue if you really want dev version in Maven Central )
use with jaxb2-maven-plugin
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>jaxb2-maven-plugin</artifactId>
<version>2.3</version>
<dependencies>
<dependency>
<groupId>be.redlab.jaxb</groupId>
<artifactId>swagger-jaxb</artifactId>
<version>1.5-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>javax.xml.parsers</groupId>
<artifactId>jaxp-api</artifactId>
<version>1.4.5</version>
</dependency>
<dependency>
<groupId>com.sun.xml.parsers</groupId>
<artifactId>jaxp-ri</artifactId>
<version>1.4.5</version>
</dependency>
<dependency>
<groupId>com.sun.xml.bind</groupId>
<artifactId>jaxb-xjc</artifactId>
<version>2.2.11</version>
</dependency>
<dependency>
<groupId>com.sun.xml.bind</groupId>
<artifactId>jaxb-core</artifactId>
<version>2.2.11</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</pluginManagement>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>jaxb2-maven-plugin</artifactId>
<version>2.3</version>
<executions>
<execution>
<id>internal.generate</id>
<goals>
<goal>xjc</goal>
</goals>
<configuration>
<arguments>-swaggerify</arguments>
<clearOutputDir>true</clearOutputDir>
<packageName>be.redlab.jaxb.swagger.generated.model</packageName>
<sources>
<source>${project.basedir}/src/main/xsd/schema</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>This one deals with a lot of my concerns and does its job but I was still not satisfied with the solution, so I forked this repository and made my changes on it.
The contribution
Here is the repository with my changes:
nandorholozsnyak
/
swagger-jaxb
JAXB XJC Plugin for automatically adding annotations from Swagger to generated classes from an XSD
swagger-jaxb
JAXB XJC Plugin for automatically adding annotations from Swagger to generated classes from an XSD
Tests run in separate project, see here for the code https://github.com/redlab/swagger-jaxb-tck
What does it do?
When you are using XSD to generate your DTO classes you may want to annotate them to make it as detailed as possible for the clients whose are going to use your endpoints.
The XSD to Java classes generation can be extended with this tool to make your API objects as declarative as they can be.
The generated classes and methods will be annotated with the proper Swagger annotation, classes with @ApiModel and methods with @ApiModelProperty.
Example
Example XSD object:
<xsd:complexType name="LoginRequestType">
<xsd:annotation>
<xsd:documentation xml:lang="en">Login object containing the e-mail and password</xsd:documentation>
</xsd:annotation>
<xsd:complexContent>
<xsd:sequence>
<xsd:element name="email" type="xsd:string">
<xsd:annotation>
<xsd:documentation xml:lang="en">E-mail of the user</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="password" type="xsd:string">
<xsd:annotation>
<xsd:documentation xml:lang="en">Password of the user with SHA512 encoding</xsd:documentation>
</xsd:annotation>A detailed README.MD and some examples are provided, most of the features are covered by unit tests, but not all, the codes by redlab and by Andreas were a bit reworked but not all.
In my projects right now I use Springfox for Swagger functionality and with this little plugin all of my DTOs which take part in the communication with the clients are detailed.
If you are interested in a extended XSD2Java class generation with Swagger then this is your time to pull this dependency into your pom.xml and start generating :)
Summary
Thank you for everybody who read my first blog post, I really appreciate it, and because I'm really new to writing I'm eager for some feedback in the comment section.
I'm curious if anybody is still using XSD schemas to generate their Java classes or maybe JSON schemas took over (btw I validate the incoming request against these schemas, so there is no surprise in the business logic ;))
Let me know what do you guys think about that and feel free to open issues or PR's.
I try to maintain the code, the code quality is not the best, I'm still wondering on a lof of refactor options but for know, it is okay to use, as I will use it from now ;)
Latest comments (0)