Springboot:使用swagger便于协同开发
一、swagger简介
这里我在网上查了发现的大部分介绍swagger
都是长篇大论,太过官方,这里简单概括:swagger
是一款能够快速生成接口文档,接口注释的优秀工具
二、springboot整合swagger
1、导入pom
<!-- springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、编写配置类,将Docket注入容器中
这里自己可以重写一个ApiInfo,更改属于自己的swagger简介
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//作者信息
public static final Contact DEFAULT_CONTACT = new Contact("kexing", "https://kexing.site/", "1600342330@qq.com");
//swagger信息
private ApiInfo apiInfo(){
return new ApiInfo(
"kexing's swagger 文档",
"不试试怎么知道",
"v1.0",
"https://kexing.site/",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
//配置swagger的Docket实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("可星")
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage:执行扫描的包
//any():扫描全部
//none():不扫描
//withClassAnnotation():扫描类上的注解
//withMethodAnnotation():扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("site.kexing"))
.build();
}
三、设置sawgger的运行环境、多人协作
@Bean
public Docket docket(Environment environment){
/**
* 希望swagger在自己设置的环境中运行
*/
//设置swagger的环境
Profiles profiles = Profiles.of("dev","test");
//判断当前环境是否在swagger设置的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("可星")
.enable(flag)
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage:执行扫描的包
//any():扫描全部
//none():不扫描
//withClassAnnotation():扫描类上的注解
//withMethodAnnotation():扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("site.kexing"))
.build();
}
通过profiles
可以设置swagger
能运行的环境,一般是开发和测试,当项目上线就不允许访问了,然后通过environment.acceptsProfiles
可以判断swagger
的环境与此时的项目环境是否一致,返回一个boolean
,最后通过enable(flag)
即可控制swagger
的开启
注入多个bean,通过groupName设置组名,然后设置一些上面的相关配置即可完成多人协作
//多人协同开发 注入多个docket
@Bean
public Docket guofubing_docket(){
return new Docket(DocumentationType.SWAGGER_2).groupName("guofubing");
}
四、生成接口文档、接口测试
User
:
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户实体类")
public class User {
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "密码")
private String password;
}
@ApiModel
设置实体类的注释信息,@ApiModelProperty
设置属性的注释信息
UserController
:
@Controller
@Api(tags = "用户控制器")
public class UserController {
//只要接口返回了实体类 swagger就会有显示
@ResponseBody
@PostMapping(value = "/user")
public User getUser(){
return new User("kexing","123");
}
@ResponseBody
@GetMapping(value = "/getuname")
public String getUsername(String username){
return username;
}
@PostMapping(value = "/topage")
@ApiOperation(value = "返回测试视图")
public String toPage(){
return "test";
}
}
控制器也可以设置注释信息,通过@Api
,@ApiOperation
注解完成