swagger 笔记

1. 新建一个 Spring Boot 项目
2. 导入 swagger 相关依赖

   
       io.springfox
       springfox-swagger2
       2.9.2
   
   
   
       io.springfox
       springfox-swagger-ui
       2.9.2
   
   

3. 编写 Controller 类
4. 编写 Swagger 配置类

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
   }
   

打上 @EnableSwagger2 注解后，就可以访问 swagger 为我们生成的接口文档了。

文档地址：http://localhost:8080/swagger-ui.html

1.自定义一个注解

@Target(value = {ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyIgnoreAnnotation {
    String value() default "";
}

2.在要忽略的api上打上该注解

@RestController
public class MyController {

    @MyIgnoreAnnotation
    @PostMapping("/get")
    public String postGet(String name, String age) {
        return "post_get";
    }

    @MyIgnoreAnnotation
    @GetMapping("/get")
    public String get(String a) {
        return "get";
    }

}

3.对自定义注解的功能进行配置，实现忽略被该注解标注的接口

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket() {

        Docket docket = new Docket(documentationType.SWAGGER_2);
        docket.apiInfo(adminApiInfo()); // api文档的描述信息
        docket.select()
                .apis(Predicates.not(RequestHandlerSelectors.withMethodAnnotation(MyIgnoreAnnotation.class))) // 自定义注解实现接口忽略
                .apis(RequestHandlerSelectors.basePackage("com.ai.swaggertest"))
                .build();

        return docket;

    }

    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统接口")
                .version("1.0")
                .contact(new Contact("John Wick", "https://baidu.com", "593635848@qq.com"))
                .build();
    }

}

可以通过 apis() 方法设置哪个包中内容被扫描。

@Bean
public Docket getDocket() {
    return new Docket(documentationType.SWAGGER_2)
            .apiInfo(adminApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.ai.swaggertest.controller"))
            .build();
}

若包路径没有指定正确，则不会在 api 文档中显示该包下的 api：

则对应的 swagger 页面为：

若包路径指定正确，则可以显示该包下的 api 。

通过 paths() 可以设置满足什么样规则的 url 被生成接口文档，可以使用正则表达式进行匹配

1.定义接口如下：

@RestController
public class MyController {

    @PostMapping("/get/hello")
    public String postGet(String name, String age) {
        return "post_get";
    }

    @GetMapping("/get/hi")
    public String get(String a) {
        return "get";
    }

    @GetMapping("/post/hola")
    public String post(String a) {
        return "post";
    }

    @GetMapping("/push/hola")
    public String push(String a) {
        return "push";
    }

}

2.编写 swagger 配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        Docket docket = new Docket(documentationType.SWAGGER_2);
        
        docket.apiInfo(adminApiInfo()); // api文档的描述信息
        
        docket.select()
        		// 在文档中呈现以“/get/”或者“/push/”开头的api
                .paths(Predicates.or(PathSelectors.regex("/get/.*"), PathSelectors.regex("/push/.*")))
                .build();

        return docket;
    }

    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统接口")
                .version("1.0")
                .contact(new Contact("John Wick", "https://baidu.com", "593635848@qq.com"))
                .build();
    }

}

生成的接口文档如下：

@ApiIgnore 可以打在类、方法和方法参数上。打在类上，可以在文档隐藏该（控制器）类。打在方法参数上，则可以在文档中隐藏该方法参数。

原来的代码：

@RestController
public class MyController {

    @PostMapping("/get")
    public String postGet() {
        return "post_get";
    }

    @GetMapping("/get")
    public String get(String a) {
        return "get";
    }

}

加上注解后：

@RestController
public class MyController {

    @ApiIgnore
    @PostMapping("/get")
    public String postGet() {
        return "post_get";
    }

    @GetMapping("/get")
    public String get(String a) {
        return "get";
    }

}