In the era of separation of front and back ends, communication between front-end developers and back-end developers is particularly important. If timely and effective communication is not achieved, it may cause the back-end developed interface to be unavailable to the front-end personnel, resulting in back-end developers having to rework and even prolong the development cycle.
Before I learned about swagger, I wrote a txt file for the interface, and wrote the interface address, parameter transfer, and return data to the front-end staff. This is an effective way to communicate, but it still seems a bit cumbersome until I understand swagger.
Those who know swagger must know what swagger can do, and those who don’t know Baidu themselves.
Now we are ready to set up the swagger environment.
1. Create a new springBoot project
After the project is completed, write a controller to ensure that the project can be started normally and successfully accessed.
2. Swagger dependency
<!--集成swagger-->
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
I use the swagger plug-in integrated with speingBoot. Of course, you can also go to maven to find pure swagger dependencies, but be careful not to import swagger-UI dependencies.
3. After the dependency is imported, we need to enable swagger.
If you want to use swagger as soon as possible and don't want to know too much about the configuration properties of swagger, you can directly add the @EnableSwagger2Doc annotation to the springBoot startup class, so that you can use http://localhost:8080/swagger-ui after you start the project. html access to swagger interface.
@SpringBootApplication
@EnableSwagger2Doc
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
But when you want to display more customized displays through swagger configuration, you have two options.
One is to set the swagger properties directly through the configuration file (this step still needs to add @EnableSwagger2Doc annotation to the startup class)
swagger:
#启动swagger
enabled: true
#界面title显示
title: Swagger接口文档插件
#界面描述
description: 这是X项目的接口文档
#要扫描的包
base-package: com.nxw
#版本信息
version: v1.0
#开发者信息
contact:
name: nxw
email: [email protected]
url: http://www.baidu.com
Please see the page after configuration.
You can clearly see the difference between after configuration and before configuration. After configuration, more properties about the document are displayed. The most important point is that after configuring the scan package, the basic-error-controller and Models interface descriptions that appeared before are not displayed. So by configuring, we can freely control the interface that we want the front-end to see by scanning, and even divide it into different groups, and different developers see differently.
The second is to achieve the same effect as the configuration file by writing the configuration class (this method does not need to add the @EnableSwagger2Doc annotation to the startup class).
The @EnableSwagger2 annotation needs to be added to the configuration class.
Not much to say, code
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket adminConfig(){
//new一个Docket，不知道这是干啥的可以看源码
Docket docket = new Docket(DocumentationType.SWAGGER_2);
//启动swagger
docket.enable(true);
//组名
docket.groupName("admin");
//开发人员信息
docket.apiInfo(adminConcat());
docket.select()
//设置扫描包
.apis(RequestHandlerSelectors.basePackage("com.nxw.controller"))
.build();
return docket;
}
@Bean
public ApiInfo adminConcat(){
return new ApiInfoBuilder()
.description("这是swagger描述")
.version("V1.0")
.title("Swagger配置测试--这是title")
.contact(new Contact("admin","http://www.baidu.com","[email protected]"))
.build();
}
}
After the configuration is complete,
you can see that there are two groups in the red frame in the figure. Choose the corresponding group and you can see different interface information. So how is this function implemented?
Actually, swagger has already thought of these functions for us. We just need to add a few more Doctkets. Look at the code.
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket adminConfig(){
Docket docket = new Docket(DocumentationType.SWAGGER_2);
docket.enable(true);
docket.groupName("admin");
docket.apiInfo(adminConcat());
docket.select()
.apis(RequestHandlerSelectors.basePackage("com.nxw.controller"))
.build();
return docket;
}
@Bean
public ApiInfo adminConcat(){
return new ApiInfoBuilder()
.description("这是swagger描述")
.version("V1.0")
.title("Swagger配置测试--这是title")
.contact(new Contact("admin","http://www.baidu.com","[email protected]"))
.build();
}
@Bean
public Docket web1Config(){
Docket docket = new Docket(DocumentationType.SWAGGER_2);
docket.enable(true);
docket.groupName("web1");
docket.apiInfo(web1Concat());
docket.select()
.apis(RequestHandlerSelectors.basePackage("com.nxw.web1Controller"))
.build();
return docket;
}
@Bean
public ApiInfo web1Concat(){
return new ApiInfoBuilder()
.description("这是swagger描述")
.version("V1.0")
.title("Swagger配置测试--这是title")
.contact(new Contact("web1","http://www.baidu.com","[email protected]"))
.build();
}
}
The above is the basic configuration of swagger. After completing the above configuration, you need to know more about the annotations of swagger to be handy.
Download address for this project: https://download.csdn.net/download/nxw_tsp/12406456