Springboot集成Swagger2

Swagger2使用说明

1、swagger2作用

​ 接口管理工具，是一套规范项目接口，帮接口自动生成接口文档。方便各个系统之间的调用，方便各方系统。

​ 提供ui界面，方便开发人员进行测试，节省开发人员大部分的时间。

---

2、spring 集成swagger2

2.1 引用 springfox 包

		<!-- swagger的依赖-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.7.0</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.7.0</version>
		</dependency>

2.2 涉及到的实体类以及controller

​ Customer.java 实体类

@Data
@AllArgsConstructor
@NoArgsConstructor
@ToString
public class Customer {
    private String name;
    private String password;

}

​ CustomerController.java Customer相关的Controller类

@RestController
@Slf4j
public class CustomerController {
    @GetMapping("/login")
    public String login(String name,String password ){
        return "Hello " + name +"|||  " + password;
    }
}

2.3 启动类中添加注解

---

​ 启动类中添加注解@EnableSwagger2 表明整个SpringBoot工程中启用Swagger2，此时就已经可以在浏览器中输入http://localhost:8080/swagger-ui.html访问简易的页面（具体的需要进行配置类的定义）

​ SpringApplication.java中

@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {

	public static void main(String[] args) {
		SpringApplication.run(SwaggerApplication.class, args);
	}

}

---

​ swagger-ui页面展示

​ 图片可以看到很多地方都是默认的英文，这时候需要添加配置类，让接口说明看的很通俗、直观

3、Swagger2的配置

3.1 编写Swagger2 配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @PROJECT_NAME: spring-swagger
 * @DESCRIPTION:
 * @USER: NORTHKING
 * @DATE: 2020/10/22 20:21
 */
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select().build();
    }

    private ApiInfo swaggerDemoApiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact("nick,sky", "www.baidu.com", "nick.sky@163.com"))
                // 标题
                .title("这是测试Swagger的标题")
                // 描述
                .description("这是测试Swagger的描述")
                // 版本
                .version("1.0.0")
                .build();
    }
}

​ Docket：摘要对象，通过对象配置描述文件的信息。 apiInfo:设置描述文件中 info。参数类型 ApiInfo

select()：返回 ApiSelectorBuilder 对象，通过对象调用 build()可以 创建 Docket 对象

ApiInfoBuilder：ApiInfo 构建器

访问url: http://localhost:8081/swagger-ui.html现在的界面是这个样子

3.2 设置扫描的包

​ 在swagger配置文件中没有配置扫描包，那么就会把整个工程中所有的接口扫描到并写入swagger-ui页面中

    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
//                .apis(RequestHandlerSelectors.basePackage("com.nicksky.swagger.controller")) //设置扫描的包
                .build();
    }

对应的swagger-ui.html页面如下

---

设置了扫描包的配置，则不会扫描到其他包的接口

    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.nicksky.swagger.controller")) //设置扫描的包
                .build();
    }

设置时候对应的swagger-ui.html页面如下

3.3 设置自定义接口配置

	自定义注解，用于方法之上，标注扫描该方法

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * @PROJECT_NAME: spring-swagger
 * @DESCRIPTION:   swagger不扫描注解
 * @USER: NORTHKING
 * @DATE: 2020/10/22 21:06
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NoSwaggerAnnotion {
}

​ 在swaggerConfig,java设置不扫描的方法

    @NoSwaggerAnnotion
    @PostMapping("/test")
    public String test(){
        return "这是controller中的test方法";
    }

	config中添加不扫描注解
	//设置包内不扫描的方法
    .apis(not(withMethodAnnotation(NoSwaggerAnnotion.class)))

这是不添加注解的swagger-ui.html扫描出的接口

这是添加@NoSwaggerAnnotion注解之后的swagger-ui.html的接口

3.4 设置接口扫描范围

​ 添加配置，是swagger扫描只扫描某些特定的接口，可以使用正则表达式

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                //设置扫描接口所在的包
               .apis(RequestHandlerSelectors.basePackage("com.nicksky.swagger.controller"))
                //设置包内不扫描的方法
                .apis(not(withMethodAnnotation(NoSwaggerAnnotion.class)))
                //设置所有的接口都可以被扫描到
//                .paths(PathSelectors.any())
                //设置以某些特定要求的接口才可以被收扫描到
                .paths(remotePath())
                .build();
    }

    private Predicate<String> remotePath() {
        return (regex("/login.*"));
    }

在controller中添加测试方法，添加注解的方法仍然不能被扫描到

    @GetMapping("/login/second")
    public String login1(String name,String password ){
        return "Hello1 " + name +"|||  " + password;
    }

    @GetMapping("/first")
    public String sss(String name,String password ){
        return "Hellosss " + name +"|||  " + password;
    }

---

在没有配置.paths（remotePath()）之前的swagger-ui.html界面是

配置之后是

​ 由此可见，我们可以设置注解来制定不扫描方法，也可以指定扫描执行的路径的方法。可以指定扫描的包以及扫描多个包，灵活性很高

4、常用的注解

4.1 @Api

​ @Api是用在类上的注解，来描述类的作用 tags：类的名称 可以有多个值 多个值表示多个副本，description:描述

@Api(tags = "这是customer相关的接口",description = "customer类接口")
public class CustomerController {···}

4.2 @ApiOperation

​ @ApiOperation是用在方法上的注解，对方法进行提示信息 value:接口描述 notes:提示信息

    @GetMapping("/login")
    @ApiOperation(value = "登录接口",notes = "输入用户名和密码")
    public String login(String name,String password ){
        return "Hello " + name +"|||  " + password;
    }

4.3 @ApiParam

​ @ApiParam 是使用在方法中的参数上，用来提示改参数的信息，是否必须等 value:信息描述 name:字段名称

require:是否必须

​ 使用@ApiParam时，必须使用@RequestParam注解，否则获取不到值。（不适用会默认是一个body,使用之后是query类型）

  @GetMapping("/login")
    @ApiOperation(value = "登录接口",notes = "输入用户名和密码")
    public String login(@ApiParam(value = "用户名",required = true,name = "name") @RequestParam String name, @ApiParam(value = "用户名密码",required = true,name = "password") @RequestParam String password ){
        return "Hello " + name +"|||  " + password;
    }

这是不使用之前，最终的结果就是获取不到值

---

这是使用@RequestParam之后的结果

4.4 @ApiModel

​ @ApiModel 是使用在类上的注解，一般用在实体类上，用于描述实体类的作用 value:名称 description:描述

@Data
@AllArgsConstructor
@NoArgsConstructor
@ToString
@ApiModel(value = "用户实体类",description = "用户")
public class Customer {
    private String name;
    private String password;

}

​ 对应的contrller 方法中必须是含有该对象

    @GetMapping("/login/second")
    public String login1(@RequestBody Customer customer ){
        return "Hello1 " + customer.getName() +"|||  " + customer.getPassword();
    }

---

4.5 @ApiModelProperty

​ @ApiModelProperty 是使用在实体类的参数或者方法上，用来描述其含义。

value：描述，name：重写属性名，required：是否是必须的，example：示例内容，hidden：是否隐藏。

@ApiModel(value = "用户实体类",description = "用户描述")
public class Customer {
    @ApiModelProperty(value = "customer实体的用户名",required = true,name = "customer.name",notes = "用户",dataType = "String")
    private String name;
    @ApiModelProperty(value = "customer实体的密码",required = true,name = "customer.password",notes = "密码",dataType = "String")
    private String password;

}

4.6 @ApiImplicitParams

​ 一般@ApiImplicitParams是和@ApiImplicitParam一起用，具体格式为：

@ApiImplicitParams({
    @ApiImplicitParam(name = "name",value = "用户名称",dataType = "String",paramType = "query"),
    @ApiImplicitParam(name = "password",value = "用户密码",dataType = "String",paramType = "query")}
                  )

4.7 @ApiImplicitParam

name–参数ming 
value–参数说明 
dataType–数据类型 
paramType–参数类型  一定要加，否则会默认类型为body,获取不到值
example–举例说明	

​ @ApiImplicitParams({
​ @ApiImplicitParam(name = “name”,value = “用户名称”,dataType = “String”),
​ @ApiImplicitParam(name = “password”,value = “用户密码”,dataType = “String”)}
​ )
​ public String test1(String name, String password){
​ log.info(“name:” + name + " password: " + password);
​ return “name:” + name + " password: " + password;
​ }
​