Swagger2的使用

Swagger初始化

• 可以自动生成API文档
• 能够在网页上直接测试接口

基于：jdk1.8

导包：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

结合 springboot

首先配置config,开启swagger2,创建Docket对象,注入spring容器
通过查看Docket源码可以得到需要DocumentationType对象构造，
DocumentationType对象可以直接通过静态成员直接生成。
swagger页面的一些信息也需要配置ApiInfo的一些属性。

//可以通过http://localhost:8080/swagger-ui.html进行访问
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class Swagger2Config {

    //Docket创建swagger2并注入bean
    @Bean
    public Docket dpcter(){
        //通过读源码可以知道；需要传递DocumentationType对象,DocumentationType可以静态成员获得
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        //看源码得知需要配置apiInfo来设置页面信息
        docket.apiInfo(info());
        return docket;
    }

    //上面需要ApiInfo配置一些页面上的信息
    public ApiInfo info(){
        //以下信息可以通过ApiInfo这个类的源码构造函数获得
        Contact DEFAULT_CONTACT = new Contact("小凯", "https://blog.csdn.net/kaikai_gege", "1140138940@qq.com");
        ApiInfo DEFAULT = new ApiInfo(
                "小凯的Api",
                "黑夜给了我黑色的眼睛",
                "2.0",
                "https://blog.csdn.net/kaikai_gege",
                DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
        return  DEFAULT;
    }
}

这时候我们可以通过http://localhost:8080/swagger-ui.html进行访问如下：

创建多个分组

@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");
}

配置Swagger开关

Swagger一般我们只用在测试和开发环境中，上线的环境不需要因为它会影响一定的效率，所以我们需要设置一下swagger的开关

主要通过Docket类的enable()这个方法

    @Bean
    public Docket docter1(Environment environment){
        //设置swagger可以显示的环境
        Profiles p = Profiles.of("test","prod");    //测试和上线环境
        boolean b = environment.acceptsProfiles(p);

        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        docket.groupName("group1")
                .enable(b);
        return docket;
    }

自定义扫描需要接口文档的接口

select().apis(RequestHandlerSelectors.参数)方法：

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

select().paths(PathSelectors.参数)方法：

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

    @Bean
    public Docket docter2(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        docket.groupName("group2")
                //通过包扫描访问只能找到Controller下的接口
                .select().apis(RequestHandlerSelectors.basePackage("com.kai.Controller"))
                        //通过请求扫描只能扫描到/user开头的请求
                        .paths(PathSelectors.ant("/user/**"))
                .build();//一定不要忘记build不然不起作用
        return docket;
    }

接口文档注释的注解

Swagger注解：

• @Api(tags = “xxx模块说明”) 作用在模块类上
• @ApiOperation(“xxx接口说明”) 作用在接口方法上
• @ApiModel(“xxxPOJO说明”) 作用在模型类上：如VO、BO
• @ApiModelProperty(value = “xxx属性说明”,hidden = true) 作用在类方法和属性上，hidden设置为true可以隐藏该属性
• @ApiParam(“xxx参数说明”) 作用在参数、方法和字段上，类似@ApiModelProperty

POJO模块

ApiModel和ApiModelProperty接口只是注释，若是要swagger文档可以显示成员属性必须要get和set方法。

@Component
@ApiModel("UserPOJO说明")
public class User {

    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("年龄")
    private int age;
    @ApiModelProperty("性别")
    private String gender;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public String getGender() {
        return gender;
    }

    public void setGender(String gender) {
        this.gender = gender;
    }

    @Override
    public String toString() {
        return "User{" +
                "name='" + name + '\'' +
                ", age=" + age +
                ", gender='" + gender + '\'' +
                '}';
    }
}

@Api(tags = "小凯的Controller")    //作用于类上
@RestController
public class helloController {

    @Autowired
    private User user;

    @GetMapping("/hello")
    @ApiOperation("你好,世界")
    public String hello(){
        return "hello,world";    //只有在返回的接口上才能通过swagger看到
    }

    @GetMapping("/user")
    @ApiOperation("你好，user")
    public User user(){
        return user;    //只有在返回的接口上才能通过swagger看到
    }
}