Wednesday, July 14, 2021

Swagger CodeGen Sprintboot Example

 Now lets try to understand Swagger Codegen feature.

Lets say we have our yaml files i.e. Employee.yaml files and want to generate server and client stub. With the help of swagger codegen we can do this.

Lets try to do it. First you need to download the packages/jar files from the below location

for version 3

https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/

for Version 2

https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli

We are using version 3 so I downloaded the swagger-codegen-cli-3.0.27.jar and check what it can provide to us.

1
2
3
4
5
6
7
8
9
10
11
12
13
C:\program_download>java -jar swagger-codegen-cli-3.0.27.jar --help
usage: swagger-codegen [-h] Command ...
 
named arguments:
  -h, --help             show this help message and exit
 
commands:
  Command                additional help
    generate             generate
    config-help          config-help
    meta                 meta
    langs                langs
    version              version

Above help command says its help to generate stub server and client using command generate. All this can be done throught cmd prompt.

we will try to explore this item later for now if you want more information how to use it please refer to the belwo provided options.

To create a server code of springboot

https://github.com/swagger-api/swagger-codegen#generating-libraries-from-your-server

To create a client code of springboot i.e feign, jersey, httpclient

https://github.com/swagger-api/swagger-codegen#to-generate-a-sample-client-library

There is another way to use it and I believe it the best way to creat the stub and that is to use the below plugin in your spring boot maven project.

For its implementation you need to have these maven entry in your project pom.xml

for swagger version 2

1
2
3
4
5
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.21</version>
</dependency>

for swagger version 3

1
2
3
4
5
<dependency>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.27</version>
</dependency>

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.21</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/Employee.yaml</inputSpec>
                <language>spring</language>
                <configOptions>
                    <sourceFolder>src/main/java/</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Lets try to use the above in our project.

1- First create a simple springboot project using spring starter we are using STS as IDE.

2- Then add this dependencies in your application pom.xml

1
2
3
4
5
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.21</version>
</dependency>

3- Then add this plug in

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.21</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/Employee.yaml</inputSpec>
                <language>spring</language>
                <configOptions>
                    <sourceFolder>src/main/java/</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Also as i was getting error for below packages/jar
com.squareup.okhttp
com.google.gson
okio

I had added follwoing dependencies in my pom.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
         <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
         
        <dependency>
            <groupId>javax.xml.bind</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.3.1</version>
        </dependency>
        <dependency>
            <groupId>com.github.joschi.jackson</groupId>
            <artifactId>jackson-datatype-threetenbp</artifactId>
            <version>2.6.4</version>
        </dependency>

File pom.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.6.0-SNAPSHOT</version>
        <relativePath /> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.siddhu</groupId>
    <artifactId>simple-springboot-swagger-codegen</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>simple-springboot-swagger-codegen</name>
    <description>This is simple swagger spring boot example shwing codegen uses</description>
    <properties>
        <java.version>11</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        <springfox-version>2.7.0</springfox-version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
 
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-codegen-maven-plugin</artifactId>
            <version>2.4.21</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
         <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-version}</version>
        </dependency>
         
        <dependency>
            <groupId>javax.xml.bind</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.3.1</version>
        </dependency>
        <dependency>
            <groupId>com.github.joschi.jackson</groupId>
            <artifactId>jackson-datatype-threetenbp</artifactId>
            <version>2.6.4</version>
        </dependency>
 
 
        <!--<dependency>
            <groupId>io.gsonfire</groupId>
            <artifactId>gson-fire</artifactId>
            <version>1.8.5</version>
        </dependency>
 
 
        <dependency>
            <groupId>com.squareup.okio</groupId>
            <artifactId>okio</artifactId>
            <version>2.10.0</version>
        </dependency>
 
        <dependency>
            <groupId>com.squareup.okhttp</groupId>
            <artifactId>logging-interceptor</artifactId>
            <version>2.7.5</version>
        </dependency>
 
        <dependency>
            <groupId>com.squareup.okhttp</groupId>
            <artifactId>okhttp</artifactId>
            <version>2.7.5</version>
        </dependency>
 
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.8.7</version>
        </dependency>
     
         -->
 
 
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
 
    <build>
 
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-codegen-maven-plugin</artifactId>
                <version>2.4.21</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>${project.basedir}/src/main/resources/Employee.yaml</inputSpec>
                            <language>spring</language>
                            <configOptions>
                                <sourceFolder>src/main/java/</sourceFolder>
                            </configOptions>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
 
    </build>
    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>spring-snapshots</id>
            <name>Spring Snapshots</name>
            <url>https://repo.spring.io/snapshot</url>
            <releases>
                <enabled>false</enabled>
            </releases>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
        <pluginRepository>
            <id>spring-snapshots</id>
            <name>Spring Snapshots</name>
            <url>https://repo.spring.io/snapshot</url>
            <releases>
                <enabled>false</enabled>
            </releases>
        </pluginRepository>
    </pluginRepositories>
 
</project>

4- Keep your *.yaml file in side the resources folder as we have given this path
${project.basedir}/src/main/resources/Employee.yaml

Note:- for more configuraiton you can check the below url

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

execute the project from IDE

clean compile

Note: -if you are executing your mvn clean compile from the prompt and if you get this error
Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.8.1:compile (default-compile) on project simple-springboot-swagger-codegen: Fatal error compiling: invalid target release: 11

Then make sure to add JAVA_HOME varaible at your cmd prompt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
C:\STS-Workspace\simple-springboot-swagger-codegen>set JAVA_HOME=C:\Program Files\Java\jdk-11.0.10
C:\STS-Workspace\simple-springboot-swagger-codegen>echo %JAVA_HOME%
C:\Program Files\Java\jdk-11.0.10
 
C:\STS-Workspace\simple-springboot-swagger-codegen>mvn clean compile
[INFO] Scanning for projects...
[INFO]
[INFO] ------------< com.siddhu:simple-springboot-swagger-codegen >------------
[INFO] Building simple-springboot-swagger-codegen 0.0.1-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-clean-plugin:3.1.0:clean (default-clean) @ simple-springboot-swagger-codegen ---
[INFO] Deleting C:\STS-Workspace\simple-springboot-swagger-codegen\target
[INFO]
[INFO] --- swagger-codegen-maven-plugin:2.4.21:generate (default) @ simple-springboot-swagger-codegen ---
[INFO] reading from C:/STS-Workspace/simple-springboot-swagger-codegen/src/main/resources/Employee.yaml
[WARNING] Output directory does not exist, or is inaccessible. No file (.swagger-codegen-ignore) will be evaluated.
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\model\Employee.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\model\ModelAndView.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\model\View.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\DeleteEmployeeApiController.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\DeleteEmployeeApi.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\ErrorApiController.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\ErrorApi.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\GetEmployeeApiController.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\GetEmployeeApi.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\InsertEmployeeApiController.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\InsertEmployeeApi.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\UpdateEmployeeApiController.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\java\io\swagger\api\UpdateEmployeeApi.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\pom.xml
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\README.md
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\configuration\HomeController.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\Swagger2SpringBoot.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\RFC3339DateFormat.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\resources\application.properties
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\api\ApiException.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\api\ApiResponseMessage.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\api\NotFoundException.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\api\ApiOriginFilter.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\configuration\SwaggerDocumentationConfig.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\configuration\CustomInstantDeserializer.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src/main/java/\io\swagger\configuration\JacksonConfiguration.java
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\.swagger-codegen-ignore
[INFO] writing file C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\.swagger-codegen\VERSION
[INFO]
[INFO] --- maven-resources-plugin:3.2.0:resources (default-resources) @ simple-springboot-swagger-codegen ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Using 'UTF-8' encoding to copy filtered properties files.
[INFO] Copying 1 resource
[INFO] Copying 2 resources
[INFO]
[INFO] --- maven-compiler-plugin:3.8.1:compile (default-compile) @ simple-springboot-swagger-codegen ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 24 source files to C:\STS-Workspace\simple-springboot-swagger-codegen\target\classes
[INFO] /C:/STS-Workspace/simple-springboot-swagger-codegen/target/generated-sources/swagger/src/main/java/io/swagger/configuration/CustomInstantDeserializer.java: Some input files use or override a deprecated API.
[INFO] /C:/STS-Workspace/simple-springboot-swagger-codegen/target/generated-sources/swagger/src/main/java/io/swagger/configuration/CustomInstantDeserializer.java: Recompile with -Xlint:deprecation for details.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  8.667 s
[INFO] Finished at: 2021-07-14T17:45:32+05:30
[INFO] ------------------------------------------------------------------------
 
C:\STS-Workspace\simple-springboot-swagger-codegen>

The above configuration will create a SERVER springboot code for you as per your provided Employee.yaml files inside your

This is your whole springboot project created using your Employee.yaml files now take this whole code and create a new project and add this file and pom.xml and make necessary changes and make call to the original Springboot exposing this method you will get the output.

Lets do that now

1- Create a Swagger2SpringBoot spring boot project with simple spring web as dependencies and packages as io.swagger
2- Copy all the files from our simple-springboot-swagger-codegen C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources to our this newly created Swagger2SpringBoot project.
3- Add requuired dependecies in pom.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-version}</version>
        </dependency>
         
        <dependency>
            <groupId>javax.xml.bind</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.3.1</version>
        </dependency>
        <dependency>
            <groupId>com.github.joschi.jackson</groupId>
            <artifactId>jackson-datatype-threetenbp</artifactId>
            <version>2.6.4</version>
        </dependency>
        

4- Copy the application.properties from C:\STS-Workspace\simple-springboot-swagger-codegen\target\generated-sources\swagger\src\main\resources\application.properties to our new created springboot project
5- Compile our create Swagger2SpringBoot using clean install or clean build
6- Execute the project as springboot and check the url
http://localhost:8080/swagger-ui.html

Note :- You can download the code from the belwo url.

simple-springboot-swagger-codegen

https://github.com/shdhumale/simple-springboot-swagger-codegen.git

Swagger2SpringBoot
https://github.com/shdhumale/Swagger2SpringBoot.git

Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)