Swagger的配置，使用与UI界面优化

前言

作为一名后端，我经常需要去测试我编写的接口，常用的有postman，idea插件RestfulTool，以及这篇文章介绍的Swagger文档。
Swagger文档不仅可以用来测试，在我看来，它是我们后端与前端的沟通桥梁，能规范我们的接口操作说明，提高前后端分离程度。

一、配置Swagger

添加依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>

Swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("CZF的swagger文档")
                .description("这是swagger的一个测试例子")
                .contact(new Contact("czf",null,"123@qq.com"))    //联系人信息
                .version("V9.99")
                .build();
    }
}

apiInfo()的展示

Swagger配置扫描接口

@Bean
public Docket docket(){
    return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
            .enable(swaggerProperties.getEnable())
        	// 定义是否开启swagger，false为关闭，可以通过变量控制
        	.apiInfo(apiInfo())
			// 将api的元信息设置为包含在json ResourceListing响应中。 
        	.host(swaggerProperties.getTryHost())
        	// 接口调试地址
            .select()
        	//通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.czf.swagger.controller"))
            /*
            RequestHandlerSelectors.any()   扫描所有，项目中的所有接口都会被扫描到
            RequestHandlerSelectors.none()  不扫描接口
            withMethodAnnotation(final Class<? extends Annotation> annotation)
            通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
            withClassAnnotation(final Class<? extends Annotation> annotation)
            通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
            basePackage(final String basePackage) // 根据包路径扫描接口
             */
            .paths(PathSelectors.ant("/test/**"))
            //配置如何通过path过滤,即这里只扫描请求以/test开头的接口
            /*
            any() // 任何请求都扫描
            none() // 任何请求都不扫描
            regex(final String pathRegex) // 通过正则表达式控制
            ant(final String antPattern) // 通过ant()控制
             */
            .build();
}

配置Swagger开关

1、如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

.groupName("模块一")

配置多个分组

@Bean
public Docket docket1(){
  return new Docket(DocumentationType.OAS_30).groupName("group1");
}

@Bean
public Docket docket2(){
  return new Docket(DocumentationType.OAS_30).groupName("group2");
}

@Bean
public Docket docket3(){
  return new Docket(DocumentationType.OAS_30).groupName("group3");
}

二、使用

1、在启动类上添加注解

@EnableOpenApi

2、在JavaBean实体类上添加注解

注解	说明
@ApiModel	用在JavaBean类上，说明JavaBean的 用途
@ApiModelProperty	用在JavaBean类的属性上面，说明此属性的的含议

3、在Controller接口类上添加注解

 @Api
 放在请求的类上，与 @Controller并列，说明类的作用，如用户模块，订单类等。 
 tags="说明该类的作用" 

4、在接口类方法上添加注解

 @ApiOperation："用在请求的方法上，说明方法的作用" value="说明方法的作用" notes="方法的备注说明" 

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
	@ApiImplicitParam：对单个参数的说明	    
	    name：参数名
	    value：参数的说明、描述
	    required：参数是否必须必填
	    paramType：参数放在哪个地方
	        · query --> 请求参数的获取：@RequestParam
	        · header --> 请求参数的获取：@RequestHeader	      
	        · path（用于restful接口）--> 请求参数的获取：@PathVariable
	        · body（请求体）-->  @RequestBody User user
	        · form（普通表单提交）	   
	    dataType：参数类型，默认String，其它值dataType="Integer"	   
	    defaultValue：参数的默认值

5、访问swagger页面

http://localhost:8080/swagger-ui/index.html

Swagger注解说明
https://blog.csdn.net/xiaojin21cen/article/details/78654652

Swagger 3.0配置整合使用教程
https://blog.csdn.net/weixin_44203158/article/details/109137799

三、优化Swagger文档界面

原生态的Swagger文档界面比较普通，我们可以通过引入依赖，使得我们的Swagger界面变得简洁好看易用起来。

有两种风格的界面可供我们选择，分别是：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.7</version>
</dependency>

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

访问接口都是：http://localhost:8080/doc.html（在ip端口后面加上doc.html）