Swagger code generation
API
An API is Only as Good as Its Documentation. With a lot of web services emerging, the need to have clear API documentation for adopting these services became clear. API documentation is the information that is required to successfully consume and integrate with an API. Concise and clear documentation — which allows your API consumers to adopt it into their application quickly — is no longer optional for organizations that want to drive adoption of their APIs.
Two of the biggest documentation issues that teams can run into include: maintenance and interaction between multiple web services. To avoid this we can use code generation from documentation. It can benefit the team in 2 ways.
- Speeding up the development time.
- Endpoints use definitions defined in one place. Request and response objects are following API definition.
Swagger
Swagger is an open source, human and machine readable API framework to design, build, and document APIs. Swagger contract describes what the API does, it’s request parameters and response objects, all without any indication of code implementation. Since its creation, Swagger has become the world’s most popular framework for API development, with over one million monthly downloads of the open source Swagger tools, and has evolved into the industry standard for designing and documenting RESTful APIs.
In my specific case I want to use generated code in microservices. Generated controller stubs can be reused in Spring application serving as an REST API endpoints. They include all of the API definitions with documentation and typed parameters. In service that will consume this endpoint, I want to reuse model definition from swagger file for request and response objects. The easyest way is to define them as maven dependency. Prerequisite is that the models are shared on maven repository.
Process of code generation:
- Define API definitions in yaml file with swagger syntax.
- Use maven to generate java source code from yaml file.
- Deploy artifact with models to repository, from where it can be shared among the projects.
swagger-codegen-maven-plugin
A Maven plugin to support the swagger code generation project
Project Structure
- gitignore to keep the directory clean
- pom.xml to setup the mvn build.
- yaml file that contains all the definitions from which the source code will be generated.
Gitignore
/src
/target
/generated
pom.xml
Important instructions from maven configuration.
Dependcy part
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-codegen</artifactId>
<version>${swagger.version}</version>
<scope>provided</scope>
</dependency>
Plugin part
<plugin>
<groupId>io.swagger</groupId>
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>${swagger.version}</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${swagger.definition}</inputSpec>
<language>spring</language>
<output>${basedir}/${generated.project.name}</output>
<apiPackage>${default.package}.controller</apiPackage>
<modelPackage>${default.package}.model</modelPackage>
<invokerPackage>${default.package}</invokerPackage>
<configOptions>
<sourceFolder>src/main/java</sourceFolder>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
maven compile plugin
Its used for compiling classes. As we dont need to include controllers into artifacts we will avoid them with
<exclude>**/controller/*.java</exclude>
<exclude>**/io/**</exclude>
maven.source.plugin
Deploying artifact with source code so the developer can browse through the source code when referencing if from project itself.
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
mvn project properties
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
<default.package>com.rivancic.swagger.example.api</default.package>
<swagger.definition>order.yaml</swagger.definition>
<generated.project.name>generated</generated.project.name>
<swagger.version>2.2.2</swagger.version>
<version.compiler.plugin>3.3</version.compiler.plugin>
<maven.compiler.target>1.8</maven.compiler.target>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.source.plugin.version>3.0.1</maven.source.plugin.version>
</properties>
| Property | Description |
|---|---|
| default.package | Defines the root package for the generated code. We want to use here the package of the application where the code will be used. This way is dead simple to copy controller classes over to existing project. |
| swagger.definition | Property that points to the swagger source file from which the code will be generated. |
| generated.project.name | Contains name of the folder into which the generated code will be stored. |
| swagger.language | Specifies for which framework the classes will be generated. As you can see from the definition I am using spring framework. List of all supported languages can be found here: Swagger codegen languages |
| other properties | Other properties specify basic maven build configuration and other plugin version |
Github example project
On github I hosted a minimalistic project for generation of java API models with deployment to maven archive.
Make a branch without gitignore file so you can see what is being generated.
