preface
Whether Spring Boot integration or spring MVC integration, Swagger is basically similar. The focus is on configuring Swagger, and its essence is configuration. @
catalogue
- 1. About Swagger
- 2. Possible problems before integration
- 3. SpringBoot integration Swagger
- 4. Configure Swagger
1. About Swagger
At present, the separation of front and rear ends in the Internet era has become a trend. The front and rear ends are mixed together. The front end or back end cannot "negotiate in time and solve it as soon as possible", which eventually leads to the centralized outbreak of problems. The solution is that the front and back ends interact through the API to achieve relatively independent and loose coupling. Swagger is such an API framework. Swagger supports many languages, such as Java, PHP, etc. it is known as the most popular API framework in the world!
2. Possible problems before integration
1, After importing the dependent jar package, use the annotation to say that it cannot be found. If it is encountered, please refer to: Summary of solutions to all Intellij IDEA Cannot Resolve Symbol XXX problems
2, There are many versions of SpringBoot and many integrated frameworks. There may be various bugs if the version is higher or lower. This is a common problem in integrating other frameworks. We should pay attention to it here. If there are some bugs in the operation, if you don't know much about the underlying principle of SpringBoot, you can Google Baidu first. If you can't find any suggestions, you might as well change the version of SpringBoot!
3. SpringBoot integration Swagger
Note: swagger2 can only be run with JDK above 1.8
1, Import two jar package 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>
2, To use Swagger, you must write a configuration class to configure Swagger. The configuration classes here are as follows
This code is by Java Architect must see network-Structure Sorting
@Configuration //This is a configuration class
@EnableSwagger2// This annotation enables automatic configuration of Swagger2
public class SwaggerConfig { //Any class name
}3, At this time, the preliminary integration has been completed, and the startup project can be accessed http://localhost:8080/swagger-ui.html, you can see the interface of swagger, as follows;
4. Configure Swagger
Whether it is Spring Boot integration or spring MVC integration, Swagger is basically similar. The key is to configure Swagger. Its essence lies in configuration, which is the key. Let's take a global look at the four key layouts of Swagger from the following figure:
4.1 Swagger four part layout
Swagger instance Bean is a Docket, so swagger must be configured by configuring the Docket instance.
The first part -- API grouping: if the grouping is not configured, the default is default. Grouping can be configured through the groupName() method of Swagger instance Docket Part 2 - Basic Description: the document information can be configured through the ApiInfo instance parameter in the apiInfo() method of the Swagger instance Docket The third part -- request interface list: within the group, any request scanned and matched by Swagger2 will appear here. Part IV - entity list: as long as the entity is on the return value of the request interface (even generic), it can be mapped to the entity item!
Part IV note: it is not because the @ ApiModel annotation makes the entity appear in the Models list, but as long as the entity that appears on the return value of the interface method will be displayed here, and the @ ApiModel and @ ApiModelProperty annotations only add annotations to the entity. The former annotates the class and the latter annotates the class properties.
4.2 Part II: API basic information
Start with the second part, which is helpful to understand the first part.
@Configuration
@EnableSwagger2
@ComponentScan("com.yichun.swagger_boot_demo.controller")
public class SwaggerConfig {
@Bean
public Docket docker(){
// The constructor passes in the initialization specification, which is the swagger2 specification
return new Docket(DocumentationType.SWAGGER_2)
//Apiinfo: add api details. The parameter is a parameter of apiinfo type. This parameter contains all the information in the second part, such as title, description and version. These information are generally customized during development
.apiInfo(apiInfo())
.groupName("yichun123")
//Configure whether Swagger is enabled. If false, it will not be accessible in the browser. The default is true
.enable(true)
.select()
//apis: add filter conditions,
.apis(RequestHandlerSelectors.basePackage("com.yichun.swagger_boot_demo.controller"))
//Paths: here is the api that controls which paths will be displayed. For example, the parameter below is that all paths except / user will generate api documents
.paths((String a) ->
!a.equals("/user"))
.build();
}
private ApiInfo apiInfo(){
Contact contact = new Contact("name: name", "Personal link: http://xxx.xxx.com / "," email: XXX ");
return new ApiInfo(
"Title Content", // title
"Description content", // describe
"Version content: v1.0", // edition
"Link: http://terms.service.url / ", / / organize links
contact, // contact information
"permit: Apach 2.0 ", // permit
"License link: XXX", // License connection
new ArrayList<>()// extend
);
}
}1. Analysis
2. RequestHandlerSelectors filtering
Click the source code of RequestHandlerSelectors, and the analysis is as follows:
4.3. Part I: configuring API grouping
In fact, the above content is a complete API Group
1. Configure a group As we said before, if the grouping is not configured, the default is default. The grouping can be configured through the groupName() method of the dock of the Swagger instance. The code is as follows:
This code is by Java Architect must see network-Structure Sorting
@Bean
public Docket docket2(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // Configure basic API information
.groupName("hello") // Configure grouping
// Omit configuration
}2. How to configure multiple groups Very simple. To configure multiple groups, you only need to configure multiple docks. The code is as follows:
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("Group I")
// Omit configuration
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("Group II")
// Omit configuration
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("Group III")
// Omit configuration
}4.4 common notes of Swagger2
Before talking about the third and fourth parts, it is very necessary to understand the common annotations of swagger2. With annotations, you can add some configuration information to some difficult attributes or interfaces to make it easier for people to read! This is also the top priority of swagger2!
First of all, we need to know that all the annotations of Swagger are defined in io Swagger. Annotations package., Only some common notes are listed here, as follows:
If you want to know more about these annotations, you can refer to swagger2 notes
4.5. Part III: API request list
Request interface list: within the group, any request that is scanned and matched by Swagger2 will appear here. Using annotations can better improve reading.
4.6. Part IV: API entity list
As mentioned earlier, as long as the entity is on the return value of the request interface (even generic), it can be mapped to the entity item! Yes, so our first step is to have entity classes first.
1, Let's create a random entity class first
@ApiModel("User entity class")
public class User {
@ApiModelProperty("Gender")
public String sex;
@ApiModelProperty(value ="user name",allowableValues = "11,12")
public int name;
}Of course, there are many properties and pits in the @ ApiModelProperty annotation. Note here that this article will not outline it for the time being.
2, As long as the entity can map to the entity item on the return value of the request interface (including generics), we write the following code:
@GetMapping("/User2")
public User getUser2(){
return new User();
}The effects are as follows:
This article is very simple. If there is anything wrong, you are welcome to criticize and correct it. Thank you very much! reference resources: https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdUG0w