SpringBoot集成Swagger UI从零搭建 + 配置 + 使用说明
导航
Swagger介绍
基于RestFul 风格的文档自动生成工具;
可以实现API定义与API文档同步更新;
简化团队项目中API开发;
支持在线测试API接口;
Swagger图解
Swagger-ui界面
SpringBoot集成Swagger UI
新建SpringBoot项目
其中Group(GruopID)一般为 域名+公司名称(例如org.apache)
Artifact(ArtifactID)一般为 项目或者模块名称 (例如swagger)
Version 表示当前项目的版本
GruopID+ArtifactID+Version 俗称坐标,可以唯一标识一个Maven项目需要勾选Spring Web(或Spring Web Starter)
点击finish,完成
整合Swagger
在pom.xml中加入Swagger依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
为方便后续配置Swagger,创建一个Swagger配置类
@Configuration//声明当前类为配置类
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {
}
启动项目,访问默认端口+/swagger-ui.html,出现如下页面,说明配置成功
例:http://localhost:8080/swagger-ui.html
此时只有基本的error处理器当我们新增了一个/hello 的API时
@RestController
public class HelloController {
@GetMapping(value = "/hello")//推荐写法
//@RequestMapping(value = "/hello",method = RequestMethod.GET) 等价于以上写法
public String Hello(){
return "hello";
}
}
配置Swagger信息
@Configuration//声明当前类为配置类
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {
//修改默认配置bean
@Bean
public Docket myDocket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
return new ApiInfo(
"测试文档",//swagger标题
"A-p-i-A-p-i-A-p-i",//swagger描述
"v1.0",//swagger版本
"https://swagger.io/",//服务条款Url
new Contact("robot001","www.baidu.com","@email"),//联系人信息
"Apache 2.0",// 许可证
"http://www.apache.org/licenses/LICENSE-2.0",// 许可证Url
new ArrayList<>()
);
}
}
重新运行发现Swagger配置信息已更改
配置Swagger扫描路径
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//配置Swagger信息
// .enable(false)//是否启用Swagger---true:(默认)正常使用;false:禁用,页面显示无法加载.
select().apis(RequestHandlerSelectors.basePackage("com.ahy.swagger.controller"))//--->设置需要扫描的包
// .select().apis(RequestHandlerSelectors.any())//--->扫描所有
// .select().apis(RequestHandlerSelectors.none())//--->不扫描
// .select().apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))//--->扫描带有指定注解的类
// .select().apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))//--->扫描带有指定注解的方法
.paths(PathSelectors.ant("/hello1/**"))//扫描指定路径
.build();
再次运行发现空空如也,因为我们扫描了指定包和指定路径,而这个路径不存在
根据项目环境决定是否启用Swagger
准备工作
application.properties:设置为开发环境
spring.profiles.active=dev
application-dev.properties:设置开发环境端口
server.port=8081
application-test.properties:设置测试环境端口
server.port=8082
加载Swagger之前先判断环境,开发环境可用Swagger
@Configuration//声明当前类为配置类
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {
//修改默认配置bean
@Bean
public Docket myDocket(Environment environment){
//设置需要显示Swagger的环境
Profiles profiles = Profiles.of("dev");
//判断当前是否处于设定的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//配置Swagger信息
.enable(flag)//是否启用Swagger---true:正常使用;false:禁用,页面显示无法加载
.select().apis(RequestHandlerSelectors.basePackage("com.ahy.swagger.controller"))//--->设置需要扫描的包
.build();
}
private ApiInfo apiInfo(){
return new ApiInfo(
"测试文档",//swagger标题
"A-p-i-A-p-i-A-p-i",//swagger描述
"v1.0",//swagger版本
"https://swagger.io/",//服务条款Url
new Contact("robot001","www.baidu.com","@email"),//联系人信息
"Apache 2.0",// 许可证
"http://www.apache.org/licenses/LICENSE-2.0",// 许可证Url
new ArrayList<>()
);
}
}
生产环境8081端口下可正常显示页面
其它环境下无法显示页面
多人协作,设置不同分组的Swagger
@Configuration//声明当前类为配置类
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {
@Bean
public Docket myDocket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("111");
}
@Bean
public Docket myDocket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("222");
}
@Bean
public Docket myDocket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("333");
}
}
Swagger 实体类注解
@ApiModel() 用于类
@ApiModelProperty() 用于方法,字段
@ApiModel(value = "用户实体类",description = "每个用户")
public class User {
@ApiModelProperty(value = "用户名",required = true,example = "xiaoming")
private String username;
@ApiModelProperty(value = "用户名",required = true,example = "123456")
private String password;
public String getUsername() {
return username;
}
public String getPassword() {
return password;
}
}
public class HelloController {
//接口中的返回值包含实体类,则会显示在Model中
//字段若是private修饰,需要有get方法才会显示该字段
@GetMapping("/user")
public User user() {
return new User();//不返回user则不会显示Models
}
}
Swagger接口注解
基于RestFul的请求形式
@Api()用于类
@ApiOperation()用于方法
@ApiIgnore() 用于类或方法上,可以不被Swagger显示
@ApiParam() 用于参数前,注释该参数
@Api(tags = {"用户请求控制器"})//控制器注解
@RestController
public class HelloController {
@ApiOperation(value = "User控制类",notes = "处理用户请求")//类名注解
@GetMapping("/user1/{username}")
public String user1(@ApiParam(name = "username",value = "用户名",required = true)@PathVariable String username){//参数注解
System.out.println("username = " + username);
return "hello:" + username;
}
}
请求测试如下
本文地址:https://blog.csdn.net/ROBOT_ADMIN/article/details/107138915
下一篇: PHP中cookie与session详解