Swagger框架

一、Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger可以生成各种格式的接口文档，生成多种语言的客户端和服务器端的代码，以及在线接口的调式等。

二、SpringBoot集成Swagger

1、在SpringBoot项目中添加Swagger的依赖

2、编写配置类配置Swagger

Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger。

//配置类
@Configuration
//开启Swagger2的自动配置
@EnableSwagger2
public class SwaggerConfig {

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

3、编写一个控制器，测试运行成功

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "helloWorld";
    }
}

4、访问：http://localhost:8080/swagger-ui.html    可以看到Swagger的界面

三、Swagger的配置

1、通过apiInfo()属性配置文档信息

//配置类
@Configuration
//开启Swagger2的自动配置
@EnableSwagger2
public class SwaggerConfig {

    //配置多个分组
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }


    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                //如果没有配置分组，默认是default。通过groupName()方法即可配置分组
                .groupName("apesource")
                //可以通过apiInfo()属性配置文档信息
                .apiInfo(apiInfo())
                .select()  //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.apesource.springbootswagger01.controller"))
                .build();
    }
    //配置文档信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字","http://xxx.xxx.com/联系人访问链接","联系人邮箱");
        return new ApiInfo(
                "Swagger学习",
                "学习演示如何配置Swagger",
                "V2.0",  //版本
                "http://xxx.xxx.com",
                contact,
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
            );
    }
}

四、常用注解

1、@Api：修饰整个类，描述Controller的作用

语法：@Api(tags="说明该类的作用，可以在UI界面上看到的注解"，value = "/类的访问路径", description = "类的文字描述")

2、@ApiOperation：描述一个类的一个方法，说明方法的作用

语法：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）

3、@ApiImplicitParam：一个请求参数

语法：@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”

header：请求参数的获取：@RequestHeader

query：请求参数的获取：@RrquestParam

path:请求参数的获取：@PathVariable

4、@ApiImplicitParam：多个请求参数

5、@ApiParam：单个参数描述

语法：@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”）

6、@ApiModel：用对象实体来作为入参