目录
Swagger前言
- 号称世界上最流行的api框架
- RestFul Api文档在线自动生成工具=>Api文档与Api定义同步更新
- 可以通过swagger注解给难理解的接口或属性增加注释信息
- 直接运行,可以在线测试Api接口(try it out)
- 支持多种语言:(Java、PHP……)
SpringBoot集成Swagger2
注意:使用的springboot版本为2.5.1不然容易报空指针
导入依赖
<dependencies>
<!--web项目-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--springboot测试类-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!--swagger2依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger的ui界面-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
在controller中写一个controller工程
@RestController
public class HelloController {
@RequestMapping("/hello")
public String hello(){
return "hello world";
}
}
配置swagger文件
@Configuration
//开启swagger2注解
@EnableSwagger2
public class SwaggerConfig {
}
配置swagger
注意:Swagger有一个bean的实例Docket
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//配置docket的实例
@Bean
public Docket docket(){
//作者信息
Contact contact = new Contact("大神", "https://www.baidu.com", "12345@qq.com");
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfo(
"大神的文档",//标题
"简单的描述",//描述
"1.0",//版本号
"https://www.baidu.com",//team组织网址
contact,
"Apache 2.0",//lincense
"http://www.apache.org/licenses/LICENSE-2.0",//lincenseUrl
new ArrayList()));
}
}
Swagger配置扫描接口
//配置docket的实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//配置是否启动swagger
.enable(false)
//下面三行同时使用,用于配置扫描接口
.select()
//配置要扫描接口的方式
//扫描下面controller包下的接口
.apis(RequestHandlerSelectors.basePackage("cn.tedu.swagger.controller"))
//过滤其他路径,只扫描hell0后面的路径
.paths(PathSelectors.ant("/hello/**"))
.build();
}
RequestHandlerSelectors的静态方法
- any():扫描全部
- none():全不扫描
- basePackage("cn.tedu.swagger.controller"):扫描该包下的接口
- withMethodAnnotation(GetMapping.class):扫描方法上被该注解标识的接口
生产环境使用Swagger
#application.properties文件内
#激活生产环境
spring.profiles.active=dev
#application-dev.properties文件内
server.port=8081
#application-pro.properties文件内
server.port=8082
@Bean
public Docket docket(Environment environment){
//设置要显示的swagger环境——里面传一个数组
Profiles profiles = Profiles.of("dev","test");
//若此环境属于上面的一种,那么返回true
boolean b = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.enable(b);
}
配置API文档的分组
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//分组1
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("大神");
}
//分组2
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("大牛");
}
}
models
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "hello world";
}
@PostMapping("hi")
public User hi(){
return new User();
}
}
public class User {
public String name;
public Integer age;
}
注意:只要接口中返回了实体类,那么modles中就会有对应的实体类(实体类中的属性用public修饰ui中可见属性,其他修饰符不可见)
注释用注解
@RestController
public class HelloController {
//注释接口的注解
@ApiOperation("hello接口")
@GetMapping("/hello")
public String hello(){
return "hello world";
}
@ApiOperation("hi接口")
@PostMapping("hi")
public User hi(){
return new User();
}
}
//注释实体类的注解
@ApiModel("user用户实体类")
public class User {
//注释实体类属性的注解
@ApiModelProperty("用户名")
public String name;
@ApiModelProperty("用户密码")
public Integer password;
}