Generating Java classes for Request and Response objects from Yaml file

Question

We have created a Yaml file using Swagger editor for our APIs specification which includes Base URL, endpoint, Request, Response and Header information etc.. Now I want to implement RESTful web service for these APIs. For that I am thinking of generating my Request and Response Java classes from this Yaml file and was looking for some kind of code generator, preferably a maven plugin/dependency which I could use in my Maven project. I came across this rest client with swagger which talks about using the swagger-codegen Maven plugin, but this is to generate the client which I believe is about generating the client code to consume these RESTful APIs, however my need is to generate classes to be used for service implementation. I will be using Java and Spring framework.

My question is what are the best practices for implementing the RESTful web services in Java when we have Yaml file (API spec created using Swagger editor) and which code generation tools/plugins are available to be used.

---

EDIT: Just came across this Server stub generator HOWTO, looking further into it.

Footcandle

Why not use the swagger-codegen Maven plugin? As you found yourself - this will generate the client code - which will contain your Request and Response classes as defined in the swagger spec? Nothing stops you from using those classes in your REST service implementation. By the way, most often, people write the java classes first and use swagger annotations to generate the swagger documentation, not the other way around - write the java code yourself, use automation to generate specs (e.g. swagger). – Ceraceous

Much easier if you want to refactor your code and reflect the changes in the swagger automatically. Imagine you want to rename/add/remove a filed, add a complex object in your response (e.g. you want to add an array(list) of Object X, which itself has a list of Object Y, X and Y has multiple fields etc.). It's easier to do this change in the code base using IDE refactoring etc., than writing the swagger by hand and hoping the generation will do what you want (e.g. how good is swagger at inheritance?). – Ceraceous

@hovanessyan,We already have API spec as Yaml file created through Swagger editor, so need to use that and cannot reverse it. However I have used swagger-codegen maven plugin to generate my classes and using them only. – Footcandle

Answer 1

Swagger-codegen maven plugin is a good option but I suggest you to use jhipster to generate your java project. It generates projects with latest tech stack including spring framework. You can select API-First development in your case. I used it and it was very efficient. You already have Yaml file. Put it in src/main/resources/swagger/api.yml and run

    ./mvnw generate-sources

All java codes will be generated.

Mongo

I already have the project which exposes some soap services and also uses Spring. I was planning to create a module in the same project for these REST services. Would jhipster still be a good option in that case? – Footcandle

I was looking at the Jhipster API-First development link that you mentioned. I talks about running ./mvnw generate-sources for code generation, it is not very clear to me what does it use to generate the code? Does it uses Swagger-codegen maven plugin or something provided by Jhipster? – Footcandle

Jhipster also uses swagger to generate code from yaml. But Jhipster generates extra codes like tests, spring configs, security etc. If you are new to jhipster you need read setup section before. After you installed jhipster then you need to generate a project then you can put the yaml file into project then run ./mvnw generate-sources – Mongo

Thank you Mehmet, I will go over the Jhipster to know more and try it out. – Footcandle

Answer 2

Using swagger-codegen-maven plugin like the following

<plugin>
<groupId>io.swagger</groupId>
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>2.4.29</version>
<executions>
    <execution>
        <goals>
            <goal>generate</goal>
        </goals>
        <configuration>
            <inputSpec>${basedir}/src/main/resources/swagger/project.yaml</inputSpec>
            <language>java</language>
            <configOptions>
                <sourceFolder>src/gen/java/main</sourceFolder>
                <library>resteasy</library>
            </configOptions>
        </configuration>
    </execution>
</executions>

or using openapi-generator-maven-plugin

<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>6.3.0</version>
<executions>
    <execution>
        <goals>
            <goal>generate</goal>
        </goals>
        <configuration>
            <inputSpec>
                ${project.basedir}/src/main/resources/swagger/project.yaml
            </inputSpec>
            <generatorName>spring</generatorName>
            <apiPackage>where api package is to be rendered</apiPackage>
            <modelPackage> model package </modelPackage>
            <supportingFilesToGenerate>
                Any supporting files needed                </supportingFilesToGenerate>
            <configOptions>
                <delegatePattern>true</delegatePattern>
            </configOptions>
        </configuration>
    </execution>
</executions>

Teetotaler