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@Beanpublic 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/",//服务条款Urlnew Contact("robot001","www.baidu.com","@email"),//联系人信息"Apache 2.0",// 许可证"http://www.apache.org/licenses/LICENSE-2.0",// 许可证Urlnew 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@Beanpublic 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/",//服务条款Urlnew Contact("robot001","www.baidu.com","@email"),//联系人信息"Apache 2.0",// 许可证"http://www.apache.org/licenses/LICENSE-2.0",// 许可证Urlnew ArrayList<>());}
}

生产环境8081端口下可正常显示页面
其它环境下无法显示页面

多人协作，设置不同分组的Swagger

@Configuration//声明当前类为配置类
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {
    @Beanpublic Docket myDocket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("111");}@Beanpublic Docket myDocket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("222");}@Beanpublic 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;}
}

请求测试如下