1. 自定义注解(案例)

功能需要：定义一个@KXJ注解，只要在方法或类上标注了该注解就不生成对应的接口文档

1.1 自定义注解

@Target({ElementType.METHOD,ElementType.TYPE}) //注解的作用范围(方法和类上)
@Retention(RetentionPolicy.RUNTIME)//注解的有效范围(运行时有效)
public @interface kxj {
    String value() default "";
}

1.2 配置

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

    docket.select()
            .apis(//当值为flase不生成接口文档，当值为true生成
                    Predicates.not(//对true取反
                            Predicates.or(RequestHandlerSelectors.withMethodAnnotation(kxj.class),//扫描方法上是否有@kxj注解,有返回true
                                    RequestHandlerSelectors.withClassAnnotation(kxj.class))//扫描类上是否有@kxj注解,有返回true
                    )
            ).build();

    return docket;
}

Predicates类是com.google.common.base中的一个条件判断类：

RequestHandlerSelectors类是springfox.documentation.builders提供的：主要用于选择器操作

• withClassAnnotation：扫描类上注解
• withMethodAnnotation：扫描方法上注解
• basePackage：包扫描
• ……

1.3 测试

@RestController
public class swaggertest {

    @GetMapping("/getswagger")
    public String getswagger(String user, Integer password){

        return "Get Mothed Swagger";
    }

    @PostMapping("/postswagger")
    public String postswagger(){

        return "Post Mothed Swagger";
    }

    @RequestMapping("/mothedswagger")
    @kxj
    public String mothedswagger(){

        return "Mothed Swagger";
    }
}

访问测试：

2. 内置注解

2.1 @Api注解

@Api的作用：标注在类上，描述当前类型生成帮助文档的信息。 controller中的所有接口生成的接口文档都会在tags这个list下，tags如果有多个值，会生成多个list，每个list都显示对应接口

参数：

1. tags：给当前类型定义别名
2. description：描述

例：

@RestController
@Api(tags = {"myGet","mypost"},description = "Swagger测试")
public class swaggertest {

    @GetMapping("/getswagger")
    public String getswagger(String user, Integer password){


        return "Get Mothed Swagger";
    }

    @PostMapping("/postswagger")
    public String postswagger(){


        return "Post Mothed Swagger";
    }}

2.2 @ApiOperation注解

@ApiOperation作用：标注在方法或者类上，给当前类型提供描述提示信息

参数：

1. value用于方法描述(必填项)
2. notes用于提示内容
3. tags可以重新分组

例：

@RestController
public class swaggertest {

    @GetMapping("/getswagger")
    @ApiOperation(value = "get请求swagger生成文档测试",notes = "重要提示信息")
    public String getswagger(String user, Integer password){

        return "Get Mothed Swagger";
    }

    @PostMapping("/postswagger")
    public String postswagger(){

        return "Post Mothed Swagger";
    }}

2.3 @ApiParam注解

@ApiParam注解作用：可以作用与属性、参数、方法，主要用于描述方法参数信息

参数：

• name：参数名称
• value：参数的作用描述
• defaultValue：默认值
• type：参数类型
• required：是否是必须参数
• hidden：是否隐藏
• allowMultiple：在请求时是否需要Multiple做请求的提交方式
• example：示例数据

例：

@RestController
public class swaggertest {

    @GetMapping("/getswagger")
    public String getswagger(@ApiParam(name = "用户名",value = "用户名权限验证",required = true,type = "String",example = "WQLKXJ") String user, Integer password){

        return "Get Mothed Swagger";
    }}

2.4 @Apilgnore注解

@Apilgnore作用：标注的类、方法、属性，用于忽略改类型生成接口文档

例：

@RestController
public class swaggertest {

    @GetMapping("/getswagger")
    @ApiIgnore
    public String getswagger( String user, Integer password){

        return "Get Mothed Swagger";
    }}

2.5 @ApiImplicitParam注解和@ApiImplicitParams注解

这两个注解和@ApiParam作用差不多都对参数进行文档描述

• @ApiParam：可以标注在类、方法、参数
• @ApiImplicitParam和@ApiImplicitParams只能标注在方法上
• @ApiParam先比较更详细

参数：

• name：参数名称
• value：参数的作用描述
• defaultValue：默认值
• paramType：参数类型
• dataType：数据类型
• required：是否是必须参数
• allowMultiple：在请求时是否需要Multiple做请求的提交方式
• hidden：是否隐藏
• example：示例数据

例：

@RestController
public class swaggertest {

    @GetMapping("/getswagger")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "用户名",value ="用户名权限验证",paramType = "String",required = true,example = "wql-kxj"),
            @ApiImplicitParam(name = "密码",value ="密码权限验证",paramType = "String",required = true,example = "wql-kxj")
    })
    public String getswagger(String user, Integer password){

        return "Get Mothed Swagger";
    }

2.6 @ApiModel和@ApiModelProperty

@ApiModel作用：描述一个实体类型，这个实体类型如果成为任何一个生成API帮助文档方法的返回值类型时，此注解就会被解析(标注在类上)

@ApiModelProperty：描述实体类型具体的属性，对属性解析描述(标注在属性上)

ApiModel的参数：

1. value：指定model的名称
2. description：描述
3. ……

ApiModelProperty的参数：

1. value：描述信息
2. name：指定名字
3. required：是否为必选项
4. example：示例数据
5. hidden：是否隐藏
6. dataType：数据类型
7. ……

例：

① 新建一个entity对象

@ApiModel
public class wql implements Serializable{


    @ApiModelProperty(value = "主键",name = "主键（ID）",required = false,dataType = "字符串")
    String id;


    @ApiModelProperty(value = "用户名",name = "验证",required = false)
    String name;
    
    @ApiModelProperty(value = "密码",name = "验证",required = false)
    String password;
    //此处实例get()/set()和hashCode/equals
}

@RestController
public class swaggertest2 {

    @GetMapping("/wql-kxj")
    public wql getswagger(String user, Integer password){
        return new wql();
    }

}