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