2024.5.29 Wednesday
Contents
- 16.Swagger
16.Swagger
Learning Objectives
- Understand the concept and function of Swagger
- Understand front-end and back-end separation
- Integrate Swagger in Spring Boot to automatically generate API documentation
16.1.Introduction to Swagger
16.1.1.Front-End and Back-End Separation
Mainstream solution: Vue+SpringBoot
Back-end era: The front end only managed static pages; html ==> back end. Template engine JSP => back end was the main force.
16.1.2.The Era of Front-End and Back-End Separation
- Front end -> Front-end control layer (two-way binding), view layer
- Use JSON to fake back-end data. This means the front-end project can still run without the back end.
- Back end -> Back-end control layer, service layer, data access layer
- Front end and back end interact through APIs
- Front end and back end are relatively independent and loosely coupled, and can even be deployed on different servers
16.1.3.Issues Arising
Front-end and back-end integration debugging, front end or back end cannot “negotiate in time, resolve early”, ultimately leading to a concentration of problems
16.1.4.Solution
- First define the schema [planned outline], and track the latest API in real-time to reduce integration risks;
- In the early years: specified Word planning documents;
- Front-end and back-end separation:
- Front end tests back-end interfaces: Postman
- Back end provides interfaces, needs to update the latest messages and changes in real-time
16.1.5.Swagger
- Claimed to be the world’s most popular API framework
- Restful API documentation online auto-generator => API documentation and API definition updated synchronously
- Direct operation, online testing of APIs
- Supports multiple languages (e.g., Java, PHP, etc.)
- Official website: https://swagger.io/
16.2.Integrating Swagger into Spring Boot
Integrating Swagger into Spring Boot => springfox, two jar packages
Springfox-swagger2
springfox-swagger-ui
Using swagger2: jdk version should be 1.8+
16.2.1.Create a new swagger-demo project
Add Maven support (click the plus sign to add the corresponding project in Project Structure->Modules),
As usual, modify the Maven, jdk, and Java versions in settings, and the jdk and Java versions in Project Structure. Modify the Spring Framework version in the pom to 2.7.13, add Thymeleaf dependencies in the pom.xml, and reload Maven.
Delete unnecessary files
16.2.2.Import Dependencies
16.2.2.1.springfox-swagger2
Maven Repository: io.springfox » springfox-swagger2 » 2.9.2 (mvnrepository.com)
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
16.2.2.2.springfox-swagger-ui
Maven Repository: io.springfox » springfox-swagger-ui » 2.9.2 (mvnrepository.com)
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
16.2.2.3.pom.xml
Current complete configuration file
<?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.7.13</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>swagger-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger-demo</name>
<description>swagger-demo</description>
<properties>
<java.version>8</java.version>
</properties>
<dependencies>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</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>
</plugins>
</build>
</project>
16.2.3. Create a controller folder
16.2.3.1. Create HelloController.java
package com.P47.controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@RequestMapping(value = "/hello")
public String hello(){
return "hello";
}
}
16.2.3.2. Run SwaggerDemoApplication.java
Default URL: /error
Test HelloController: http://localhost:8080/hello
16.2.4. Configure Swagger
16.2.4.1. Create a config folder, SwaggerConfig.java
package com.P47.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration // Equivalent to @Component
@EnableSwagger2 // Enable Swagger2
public class SwaggerConfig {
}
16.2.4.2. Solution for http://localhost:8080/swagger-ui.html not opening
See the blog https://blog.csdn.net/2401_83329143/article/details/138858363
Modify application.properties
spring.application.name=swagger-demo
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
16.2.4.3. Rerun SwaggerDemoApplication.java
http://localhost:8080/swagger-ui.html
16.3. Configure Swagger
The Swagger instance Bean is Docket, so configure Swagger through the Docket instance.
16.3.1. Modify SwaggerConfig.java
package com.P47.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration // Equivalent to @Component
@EnableSwagger2 // Enable Swagger2
public class SwaggerConfig {
// Configure the Swagger bean instance Docket to set up Swagger's specific parameters
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2) // Source code in DocumentationType.class, choose the version that fits
.apiInfo(apiInfo()); // Method public Docket(DocumentationType documentationType), click on ApiInfo to enter ApiInfo.class
// Click to enter Docket.class to see the source code of various methods
}
// Configure Swagger information (apiInfo)
private ApiInfo apiInfo(){
// Prevent DEFAULT_CONTACT (renamed to contact) from reporting errors
Contact contact = new Contact("Contact Name", "Contact URL", "Contact Email");
return new ApiInfo("Swagger Api Documentation", // Title
"Api Documentation Description", // Description
"version 1.0", // Version number
"http://terms.service.url", // Organization URL
contact, // Contact information
"Apache 2.0", // License
"http://www.apache.org/licenses/LICENSE-2.0", // License URL
new ArrayList<>() // Extensions
);
}
}
16.3.2. Restart
http://localhost:8080/swagger-ui.html#/
The source code of this page is located at: D:\apache-maven-3.5.4\repository\io\springfox\springfox-swagger-ui\2.9.2\springfox-swagger-ui-2.9.2.jar!\META-INF\resources\swagger-ui.html