swagger

首先导入对应的swagger依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

然后在springbooot启动类上加上开启swagger的注解即可

@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }

}

最后使用浏览器访问页面http://127.0.0.1:8080/swagger-ui.html#/

就可以看到页面了，swagger会默认扫描所有控制层

配置swagger页面的标题和注释信息，这个只需要配置一次即可,具体信息可自定义

配置信息中可以指定只扫描哪些包下的类，默认是扫描启动类下的所有子包

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder()
                .contact(new Contact("xxx公司","http://baidu.com","[email protected]"))
                .title("swagger接口文档")
                .description("用来学习swagger")
                .build();
        docket.apiInfo(apiInfo);
        //指定扫描控制层
        docket = docket.select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")).build();
        return docket;
    }
}

配置指定注解的方法上不会显示

首先创建一个自定义注解

/**
 * @author luoqing
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation {
}

然后在返回配置中设置有该注解时不显示api文档

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder()
                .contact(new Contact("xxx公司","http://baidu.com","[email protected]"))
                .title("swagger接口文档")
                .description("用来学习swagger")
                .build();
        docket.apiInfo(apiInfo);
        //指定扫描控制层
        docket = docket.select()
//                方法上有自定义类注解时取反，则不生效
                .apis(Predicates.not(RequestHandlerSelectors.withMethodAnnotation(MyAnnotation.class)))
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")).build();
        return docket;
    }
}

指定匹配的路径才显示在swagger文档中

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder()
                .contact(new Contact("xxx公司","http://baidu.com","[email protected]"))
                .title("swagger接口文档")
                .description("用来学习swagger")
                .build();
        docket.apiInfo(apiInfo);
        //指定扫描控制层
        docket = docket.select()
//                方法上有自定义类注解时取反，则不生效
                .apis(Predicates.not(RequestHandlerSelectors.withMethodAnnotation(MyAnnotation.class)))
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
//                路径是/swagger开头的才会显示在swagger文档中
                .paths(PathSelectors.regex("/swagger/.*"))
                .build();
        return docket;
    }
}

匹配多个路径

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder()
                .contact(new Contact("xxx公司","http://baidu.com","[email protected]"))
                .title("swagger接口文档")
                .description("用来学习swagger")
                .build();
        docket.apiInfo(apiInfo);
        //指定扫描控制层
        docket = docket.select()
//                方法上有自定义类注解时取反，则不生效
                .apis(Predicates.not(RequestHandlerSelectors.withMethodAnnotation(MyAnnotation.class)))
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
//                路径是/swagger开头的才会显示在swagger文档中
                .paths(Predicates.or(PathSelectors.regex("/swagger/.*"),PathSelectors.regex("/swagger2/.*")))
                .build();
        return docket;
    }
}

为每个controller指定对应的名字以及注解

@Api默认会在我们的控制器名称中加-来命名，但是我们需要自己自定义名字

@RestController
@Api(tags = "测试",description = "用来学习swagger")
public class SwaggerController {

    @MyAnnotation
    @GetMapping("/test")
    public String test(String m){
        return m;
    }


    @PostMapping("/test1")
    public String test1(String m1){
        return m1;
    }
}

@ApiOperation我们可以给整个控制器添加名字我们也可以给每一个方法添加

@PostMapping("/test1")
@ApiOperation(value = "测试2",notes = "用来测试的")
public String test1(String m1){
    return m1;
}

@ApiParam 给参数添加描述，并且设置参数为必填,这里注意，参数一定要加@RequestParam，否则有时候swagger读取不到参数

@PostMapping("/test1")
@ApiOperation(value = "测试2",notes = "用来测试的")
public String test1(@ApiParam(name = "第一个参数",value = "这里是注释",required = true) @RequestParam String m1){
    return m1;
}

@ApiIgnore也可以使用另一种swagger注解让方法不生成swagger文档，和我们上面自己写的一样

@PostMapping("/test1")
@ApiIgnore
@ApiOperation(value = "测试2",notes = "用来测试的")
public String test1(@ApiParam(name = "第一个参数",value = "这里是注释",required = true) String m1){
    return m1;
}