SpringBoot整合Swagger3

1、创建项目

• 首先创建一个SpringBoot项目，随便勾选几个项目依赖，我选择了web、thymeleaf、lombok。
  

• 添加项目依赖，这里使用Swagger3（与Swagger2略有差异），并且添加一个好看一点的ui界面

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2、配置Swagger

• Swagger最核心的类就是Docket、它可以配置作者信息、扫描类型…

• 首先创建一个SwaggerConfig配置类，添加@Configuration和@EnableOpenApi注解。

• 然后再向里面丢入Docket类的Bean实例，然后默认就可以访问了

@Configuration
@EnableOpenApi
public class SwaggerConfig {
	@Bean
    Docket docket(){
		return new Docket(DocumentationType.SWAGGER_2)
	}
}

• 访问localhost:8080/doc.html页面就可以看到了，/error接口的8种请求方式默认会出现在文档中，以及一些可以配置的信息
  

3、Swagger配置

上图红字的位置都是可以进行配置的，可以针对不同人写的不同接口等信息放在不同的分组中。

3.1、配置主页信息

其实这里有用的没几个，基本上很多信息都是默认给出。

@Bean
public ApiInfo apiInfo(){
    return new ApiInfo("这是Swagger文档",				//title名称
            "归来仍是少年",								//简介
            "1.0",										//版本
            "urn:tos",									//服务url
            new Contact(								//配置联系作者的方式
            	"xxx",									//作者名称
            	"https://www.baidu.com",				//连接
            	"xxxx@qq.com"),							//作者邮箱
            "Apache 2.0",								//许可证
            "http://www.apache.org/licenses/LICENSE-2.0",		//许可证地址
            new ArrayList<>());							//供应商的拓展
}

3.2、配置Docket信息

• 上面配置了主页面的一些信息，然后需要将这些信息注入到Docket中。

• 另外配置扫描接口的路径、过滤、分组以及是否开启等

• 当然这里可以拿到环境配置文件、可以根据不同的环境决定是否开启；一般情况下这些接口都是在开发环境中进行展示的，实际交付的时候是不会提供的。

• Docket是采用链式编程的形式进行配置，当存在多个Docket时可以通过不同的分组名称进行区分

@Bean
Docket docket_A(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("TestA");
}

@Bean
Docket docket_B (){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("TestB");
}


@Bean
Docket docket(Environment environment){

    boolean result = environment.acceptsProfiles(Profiles.of("dev"));

    return new Docket(DocumentationType.SWAGGER_2)
    		.groupName("Splay")				//默认分组Default改为Splay
            .apiInfo(apiInfo())				//注入主页面信息
            .enable(true)                   //是否启用swagger
            .select()						//扫描
            /**
             * apis指定要扫描的方式
             * 1. basePackage(): 指定扫描的包
             * 2. any(): 全部扫描
             * 3. none(): 都不扫描
             * 4. withClassAnnotation(): 通过类注解扫描
             * 5. withMethodAnnotation(): 通过方法上的注解扫描
             */
            .apis(RequestHandlerSelectors.basePackage("com.splay.controller"))
            /**
             * paths过滤不需要
             * 1. ant(): 制定路径
             * 2. none(): 全都不过滤
             * 3. any(): 都过滤
             * 4. regex(): 正则表达式
             */
            //.paths(PathSelectors.ant("/splay/**"))		//过滤不需要的路径
            .build();
}

3.3、编写Controller

上面通过apis方法配置只扫描com.splay.controller包下的所有接口

@Controller
public class RouterController {
    
    @GetMapping("/hello")
    @ResponseBody
    public String toHello(){
        return "Hello Swagger";
    }
}

• 这里可以绑定开启的环境，通过Environment拿到进行判断再决定是否开启。
  

3.4、效果图

4、注解的使用

• Swagger提供了很多的注解，几乎所有需要提供展示的东西都可以使用注解来开启。

• @Api配置Controller类、@ApiModel类可以给pojo进行展示、@ApiModelProperty配置pojo的属性、@ApiOperation配置方法…

4.1、pojo的配置

当返回值存在当前配置的pojo时，可以在model页面看到这些信息。

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户类" )
public class User {

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;

}

4.2、Controller的配置

Controller的名称将会展示为tags属性中的值

@Controller
@Api(tags = "路由控制类")
public class RouterController {
	
}

4.3、接口名称的配置

@PostMapping("/user")
@ResponseBody
@ApiOperation("返回用户信息")			//接口名称、以及参数
public User sendUserMessage(@ApiParam("用户帐号") String username){
    System.out.println(username);
    return new User("admin", "123456");
}

4.4、效果图