SpringBoot入门教程系列（三）：整合Swagger 3.0

1、添加依赖

Swagger3.0和之前版本的依赖不太一样，3.0版本只需要引入如下依赖即可。

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

2、Swagger 配置。创建SwaggerConfig类，添加@Configuration和@EnableSwagger2注解后即可使用；详细的配置如下：

/**
 * swagger配置
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment){
        //开发和测试环境
        Profiles profiles=Profiles.of("dev","test");
        //通过environment.acceptsProfiles()判断是否处在自己设定的环境当中
        boolean swaggerEnabled=environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                //多人开发时分组
                .groupName("zhou")
                //是否启用Swagger
                .enable(swaggerEnabled)
                .select()
                //基于包进行扫描
                //RequestHandlerSelectors.basePackage()//基于包进行扫描
                //RequestHandlerSelectors.any()//扫描全部
                //RequestHandlerSelectors.none()//不扫描
                .apis(RequestHandlerSelectors.basePackage("com.ykkj.springboottemplate.controller"))
                //paths()过滤什么路径
//                .paths(PathSelectors.ant("/controller/**"))
                .build();
    }

//    /**
//     * 用户A 开发的接口
//     * @param environment 环境
//     * @return Docket
//     */
//    @Bean
//    public Docket docketA(Environment environment){
//        //开发和测试环境
//        Profiles profiles=Profiles.of("dev","test");
//        //通过environment.acceptsProfiles()判断是否处在自己设定的环境当中
//        boolean swaggerEnabled=environment.acceptsProfiles(profiles);
//
//        return new Docket(DocumentationType.OAS_30)
//                .apiInfo(apiInfo())
//                //多人开发时分组
//                .groupName("A")
//                //是否启用Swagger
//                .enable(swaggerEnabled)
//                .select()
//                //基于包进行扫描
//                //RequestHandlerSelectors.basePackage()//基于包进行扫描
//                //RequestHandlerSelectors.any()//扫描全部
//                //RequestHandlerSelectors.none()//不扫描
//                .apis(RequestHandlerSelectors.basePackage("com.ykkj.springboottemplate.controller"))
//                //paths()过滤什么路径
                .paths(PathSelectors.ant("/controller/**"))
//                .build();
//    }

    /**
     * swagger配置
     * @return ApiInfo
     */
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact=new Contact("zhou","https://www.baidu.com/","zhou@126.com");
        return  new ApiInfo("Spring Boot 项目实例",
                "男儿当自强",
                "v1.0",
                "https://www.baidu.com/",
                contact,
                "",
                "",
                new ArrayList());
    }
}

3、访问Swagger地址：http://localhost:8080/swagger-ui/index.html，需要注意Swagger3.0和之前版本的访问地址是不同的。

4、给Swagger文档的接口中添加中文注释，使用@ApiOperation(“这里是注释”)注解，如：在controller中使用如下：

    @ApiOperation("问候")
	@GetMapping(path = "/greeting")
	public Res greeting(@RequestParam(value = "name",defaultValue = "world!")String name){
		Res res=new Res();
		res.setMsg("success");
		res.setData(atomicLong.incrementAndGet()+name);
		return res;
	}

5、美化Swagger UI

Swagger 自带的UI界面不是很好看，我们可以使用swagger-bootstrap-ui进行美化，添加如下依赖，重新启动，访问地址：http://localhost:8080/doc.html

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