Swagger - 个人笔记

1.导包

Maven依赖如下，版本自选（现在是2.9.2版本）：

<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>

2.在项目中配置

2.1 新建一个类作为配置类

@Component
// 开启Swagger2的自动配置
@EnableSwagger2
public class SwaggerConfig {
    
}

2.2 配置Swagger实例

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

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

    // 配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2);
    }

}

上面的配置就已经可以使用Swagger了。通过访问http://localhost:8080/swagger-ui.html（自己的项目访问路径/swagger-ui.html）来访问接口文档就可以了。（自己写几个Controller来查看）

2.3 配置API文档的信息

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

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

    // 配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }


    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        // public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String ", String licenseUrl, Collection<VendorExtension> vendorExtensions) {
        return new ApiInfo("Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()); // 扩展
    }

}

配置后重启访问可以看到如下：

2.4 配置要扫描的接口

构建Docket时通过select()方法配置怎么扫描接口。

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

    // 配置docket以配置Swagger具体参数
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 通过.select()方法，去配置扫描接口
                .select()
                // RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerexample.controller")).build();
    }


    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        // public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String ", String licenseUrl, Collection<VendorExtension> vendorExtensions) {
        return new ApiInfo("Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()); // 扩展
    }

}

除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

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

2.5 配置接口扫描过滤

上述方式可以通过具体的类、方法等扫描接口，还可以配置如何通过请求路径配置：

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
        .select()
        //.apis(RequestHandlerSelectors.basePackage("com.wts.controller")).build();
        //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)).build();
        //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)).build();
        .apis(RequestHandlerSelectors.basePackage("com.wts.controller"))
        .paths(PathSelectors.ant("/hello/**"))  //筛选路径
        .build();
    }

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

2.6 配置要忽略的请求参数

可以通过ignoredParameterTypes()方法去配置要忽略的参数：

@RestController
@RequestMapping("/hello")
public class HelloController {

    @PutMapping
    public String updateHello(String string){
        return string;
    }
    @DeleteMapping
    public String deleteHello(Integer id, Long idL, HttpSession session, HttpRequest request){
        return "hello";
    }
}

//配置要忽略的请求参数
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .ignoredParameterTypes(Integer.class,Long.class, HttpRequest.class);
    }

2.7 配置是否启动Swagger

通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了：

@Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .ignoredParameterTypes(HttpServletRequest.class)
                .enable(false) // 配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wts.controller")).build();
    }

如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

@Bean
    public Docket docket(Environment environment) {
        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是处于该环境，通过 enable() 接收此参数判断是否要显示
        boolean isEnable = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .ignoredParameterTypes(HttpServletRequest.class)
                .enable(isEnable) // 配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wts.controller")).build();
    }

2.8 配置API分组

    @Bean
    public Docket docketUser() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户")
                .select().paths(PathSelectors.ant("/user")).build();
    }
   

如下图所示，我们配置了groupName("user")那么当前接口分组信息为user。

如何配置多个分组？

配置多个分组只需要配置多个docket即可：

    @Bean
    public Docket docketUser() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .groupName("用户")
                .select().paths(PathSelectors.ant("/user")).build();
    }
    @Bean
    public Docket docketHello(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .groupName("你好")
                .select().paths(PathSelectors.ant("/hello")).build();
    }

2.9 实体配置

比如当前项目中有这么一个实体：

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("年龄")
    private int age;

    public User() {
    }

    public User(String username, int age) {
        this.username = username;
        this.age = age;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public int getAge() {
        return age;
    }

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

参数显示注释

@RestController
@RequestMapping("/user")
public class UserController {
    @GetMapping
    public String getUser(@RequestBody Cat cat){
        return "张三";
    }

全局参数的配置

@Bean
    public Docket docketUser() {
        Parameter token = new ParameterBuilder().name("token")
                .description("用户登录令牌")
                .parameterType("header")
                .modelRef(new ModelRef("String"))
                .required(true)
                .build();
        List<Parameter> parameters = new ArrayList<>();
        parameters.add(token);
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .globalOperationParameters(parameters);
    }

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释