Renato Ivancic - Software Engineer

Background image

Swagger code generation

Backend

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.

  1. Speeding up the development time.
  2. Endpoints use definitions defined in one place. Request and response objects are following API definition.

Swagger

Swagger Logo

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:

  1. Define API definitions in yaml file with swagger syntax.
  2. Use maven to generate java source code from yaml file.
  3. 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

https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen-maven-plugin/README.md

Project Structure

  1. gitignore to keep the directory clean
  2. pom.xml to setup the mvn build.
  3. 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.

Rivancic Github

Make a branch without gitignore file so you can see what is being generated.

Sources

Swagger

Swaggerhub

swagger-codegen-maven-plugin

#Swagger #Maven #Code generation #API