FirstApi approach with OpenAPI generator plugin and SpringDoc OpenAPI UI to your Spring Boot Project
Tested with Java 17 and SpringBoot 2.7.7
Add the following property version for openapitools in pom.xml:
<properties>
<openapitools.generator.version>6.4.0</openapitools.generator.version>
</properties>
Add the following dependencies:
<!--OPENAPI GENERATOR MAVEN PLUGIN-->
<dependency>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>${openapitools.generator.version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.openapitools</groupId>
<artifactId>jackson-databind-nullable</artifactId>
<version>0.2.4</version>
</dependency>
<!--SPRINGDOC OPENAPI-->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.13</version>
</dependency>
Generate your api.yaml file
You can use https://editor.swagger.io/
Generate a file called api.yaml and place it in src/main/resources
Add the following plugging in your pom.xml file
<!--OpenApi Codegen-->
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>${openapitools.generator.version}</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
<generatorName>spring</generatorName>
<generateApiTests>false</generateApiTests>
<generateModelTests>false</generateModelTests>
<modelNameSuffix>Dto</modelNameSuffix>
<configOptions>
<sourceFolder>src/gen/java/main</sourceFolder>
<oas3>true</oas3>
<useSpringController>true</useSpringController>
<useSpringfox>false</useSpringfox>
<interfaceOnly>true</interfaceOnly>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
Add the following property in application.properties file
This is optional but could avoid few future problems
spring.mvc.pathmatch.matching-strategy=ant-path-matcher
Implement the generated methods
To complete your API, you can implement the generated methods by the codegen plugging on the default path:
target/generated_sources/openapi/src/gen/java
Check Swagger UI website
Run your application and access the following url to check your API documentation:
host:port/swagger-ui/index.html
http://localhost:8080/swagger-ui/index.html
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent