Generating java model with inheritance from swagger specification
Nowadays software requires a lot of integration. Services expose their interface
and separate consumers from implementation details. Contract first approach is well known as a best practice since years, and this approach is not restricted to WSDL based web-services. Also JSON based Restful APIs may benefit from specification-first.
One of the tools that supports this approach is Swagger, which is used commonly in our projects.
After your API contract together with data model is specified, you as developer will be often tempted to reuse this definition in your code, so that you do not have to manually synchronize the formal specification and code implementing it. Swagger comes with help and provides code generator for various programming languages. We are interested mostly in generation of a Java based API client code.
Model with inheritance
Let's assume our model is like this: we have an Order, which in turn may contain one or more Order Lines, each can be an Article, a Fee representing sending cost, and a Discount. This translates to a specification (stored in a swagger.yml file) fragment that could look like this:
OrderLine:
type: object
required:
- quantity
- type
- totalValue
- unitValue
discriminator: type
properties:
quantity:
type: integer
format: int32
type:
type: string
enum:
- article
- fee
- discount
unitValue:
type: number
totalValue:
type: number
Article:
allOf:
- $ref: '#/definitions/OrderLine'
- type: object
required:
- articleNumber
- taxRate
properties:
articleNumber:
type: string
taxRate:
type: number
Fee:
allOf:
- $ref: '#/definitions/OrderLine'
- type: object
required:
- feeType
properties:
feeType:
type: string
Discount:
allOf:
- $ref: '#/definitions/OrderLine'
- type: object
required:
- discountType
properties:
discountCode:
type: string
discountType:
type: string
Example json fragment conforming to this specification can look as follows:
"orderLines" : [
{
"type": "article",
"articleNumber": "997.18",
"quantity": 1,
"unitValue": 4.99,
"totalValue": 4.99,
"taxRate": 19.0
},
{
"type": "fee",
"feeType": "payment_fee",
"quantity": 1,
"unitValue": 0.49,
"totalValue": 0.49
}
]
Why we forked swagger-codegen
Unfortunately, out-of-the-box version of _swagger-codegen_ currently **does not support** generation of valid client for our model in Java. Tooling support was not something that should prevent us from using the model we are really willing to use. Thanks to the fact _swagger-codegen_ is Open Source Software, it was possible to implement inheritance support that matches our needs. We decided to publish an enhanced version which can be find at our github repo. To use it clone the repository and just `mvn install` our fork. Upstream project plans to include our changes in version 2.2.2, so hopefully in near future you can just omit `-zoo` in the artifact name and just declare higher version. Note: our current implementation is supporting only one client implementation (which is retrofit2).How inheritance works
Crucial parts of our specification are usage of `allOf` syntax (to declare parent definition) and definition of `discriminator`. According to specification of swagger format only way to provide link between type of data and discriminator value is by keeping ==names of declared discriminator values same as child data definitions==.To support polymorphism, Swagger adds the support of the discriminator field. When used, the discriminator will be the name of the property used to decide which schema definition is used to validate the structure of the model. As such, the discriminator field MUST be a required field. The value of the chosen property has to be the friendly name given to the model under the definitions property.
Our implementation is case-insensitive, so that it is possible to recognize that "type": "article" should be mapped to Article definition.
Maven configuration
To be able to generate something we need to call _swagger-codegen_ tool and as my project uses maven, this will happen simply by adding _swagger-codegen-maven-plugin_ to `pom.xml`. This tool consumes some parameters, so first you have to take a look at documentation in _swagger-codegen_ `README` file.I am adding following snippet to my build/plugins section, it is configured to use retrofit2 library for http calls:
<plugin>
<groupId>io.swagger</groupId>
<artifactId>swagger-codegen-maven-plugin-zoo</artifactId>
<version>2.2.1.1</version>
<executions>
<execution>
<id>api-call</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>
PATH_TO_SPEC/swagger.yml
</inputSpec>
<language>java</language>
<library>retrofit2</library>
<addCompileSourceRoot>false</addCompileSourceRoot>
<configOptions>
<dateLibrary>java8</dateLibrary>
</configOptions>
<output>${project.build.directory}/generated-sources/swagger/src/main/java</output>
<apiPackage>zoo.order.api</apiPackage>
<modelPackage>zoo.order.api.model</modelPackage>
<invokerPackage>zoo.order.api.client</invokerPackage>
</configuration>
</execution>
</executions>
</plugin>
This will cause generation of client code with model classes.
Interesting aspect is that PATH_TO_SPEC can point eg. to location in artifactory, allowing us to point to shared and versioned specifications instead of just a file.
To have generated code included in application build process we need to make this files visible to maven compiler plugin. We will need build-helper-maven-plugin, configured to place where our model sources have been generated:
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>1.12</version>
<executions>
<execution>
<id>add-source</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>${project.build.directory}/generated-sources/swagger/src/main/java</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
Only thing that left is to add dependencies required by generated code:
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>converter-gson</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>converter-scalars</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>org.apache.oltu.oauth2</groupId>
<artifactId>org.apache.oltu.oauth2.client</artifactId>
<version>1.0.1</version>
</dependency>
<dependency>
<groupId>io.gsonfire</groupId>
<artifactId>gson-fire</artifactId>
<version>1.8.0</version>
</dependency>
After trivial configuration our model has been generated and we can focus on solving business issues instead of keeping our eyes on manually written clients and keeping models in sync with service specification.