SpringBoot之Swagger基础入门(Swagger UI)

---

前言

swagger是一款强大的开源框架 , 用于自动生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

功能比postman强大 , 且无需下载软件

这在前后端分离的开发中尤为重要 , 因为在这种开发模式下, 往往需要使用大量的接口进行前后端交互

---

提示：以下是本篇文章正文内容，下面案例可供参考

一、环境搭建

1. 导入jar包

直接给出Maven坐标,注意swagger-ui的坐标也要导入哦

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

2. 创建配置类

这里我们先不实现这个配置类 , 这样系统会使用默认配置,在后面会对Swagger 的配置类给出配置

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {}

注 : 只有在打上@EnableSwagger2注解,才能真正开启swagger

3. 管理后台测试是否配置成功

登录http://localhost:端口号/swagger-ui.html 查看是否配置成功

二、具体配置Swagger UI

1. 配置网页基本信息

代码如下（示例）：

//在这里配置swagger信息(私有方法)
    private ApiInfo apiInfo(){
        Contact contact = new Contact("xiaoj", "https://blog.csdn.net/qq_45596525", "1665219552@qq.com");
        return new ApiInfo(
                "Xiaoj的blog",
                "流水不争先",
                "1.0",
                "https://blog.csdn.net/qq_45596525",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }

注 : 在源码中 , 我们能找到ApiInfo类的构造方法

源码 : 
public static final ApiInfo DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos",
          DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());

我们可以直接复制来,去掉前面几个关键字 , 然后根据源码的内容讲UI的基本信息修改成我们需要的样子

但是 : DEFAULT_CONTACT是源码中设置的static final变量,我们不能直接使用,所以 , 需要在方法顶部手动初始化出Contact对象

2.配置扫描接口以及Swagger开关

注释里已经写得很清楚了

//docket对象接管容器
    @Bean
    public Docket docket(Environment environment){ //向docket容器传入环境参数
        //根据当前环境判断是否开启swagger
        Profiles profile = Profiles.of("dev","test"); //指定再开发和测试环境中开启swagger
        boolean flag = environment.acceptsProfiles(profile);//传入参数

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("xiaoj")
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                    //添加接口处理方式,扫描controller包下的内容
                    .apis(RequestHandlerSelectors.basePackage("edu.cust.cs.springboot08swagger.controller"))
                    .build(); //向docket加入apiInfo()
    }

同时还需要在.properties文件中配置出端口号,并选择环境为开发还是生产环境

配置完成之后的网页是这样的

---

三、团队用户分组

根据上图我们能发现在页面的右上角有一个下拉框, 在完成配置后我们能点击查看其它人完成的接口的文档

配置非常简单, 只需要在new Docket对象的时候加上一个groupName("用户名") 即可

四、强大的注释(接口和实体类)

1. @ApiOperation("接口名")  注释一个controller接口
2. @ApiParam("参数名") 注释一个controller接口方法中的参数名
3. @ApiModel("类名") 注释一个实体类
4. @ApiModelProperty("变量名") 注释实体类的属性名

配置成功后的页面

如果想要在页面中获取实体类对象 ,还需要在controller层中配置出一个返回值为实体类的方法且返回值也只能是要在页面显示的实体类对象 ,否则页面是取不到值的

@RestController
@ApiOperation("SwaggerController")
public class SwaggerController {
    @GetMapping("/getUser")
    public User getUser(@ApiParam("用户ID") String username){
        System.out.println(username);
        return new User();
    }
}

五、在线测试!