SpringBoot 集成 Swagger

一、SpringBoot 集成 Swagger
- 1.1 创建项目并集成Swagger
- - 1.1.1 创建项目
  - 1.1.2 导入Swgger依赖
  - 1.1.3 编写Config类
- 1.2 Swagger 相关配置
- - 1.2.1 配置是否启动Swagger
  - 1.2.2 配置Swagger 扫描接口
  - 1.2.3 配置过滤器
  - 1.2.4 配置Swagger 文档分组
- 1.3 Swagger 配置 Models
- - 1.3.1 默认配置Models
  - 1.3.2 自定义配置Models
- 1.4 Swagger 测试

一、SpringBoot 集成 Swagger

1.1 创建项目并集成Swagger

1.1.1 创建项目

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

1.1.2 导入Swgger依赖

进入Maven官网，搜索

springfox swagger

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

导入上述两个依赖

<!-- springfox-swagger UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

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

1.1.3 编写Config类

编写一个SwaggerConfig 作为SpringBoot中Swagger的配置

@Configuration
@EnableSwagger2     //开启Swagger2
public class SwaggerConfig {

}

@EnableSwagger2

直接的作用是开启Swagger2

编写完成后，启动项目，然后在浏览器访问

http://localhost:8080/swagger-ui.html

，即可进入到Swagger文档界面

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

自定义Swagger文档界面，在SwaggerConfig类中配置Swagger文档界面的相关信息

@Configuration
@EnableSwagger2     //开启Swagger2
public class SwaggerConfig {

    /**
     * 配置Swagger 的 Docket 的 Bean 实例
     * @return
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    /**
     * 配置 Swagger 信息的 apiInfo
     */
    private ApiInfo apiInfo(){
        Contact contact = new Contact("痞猫尤加利的博客","https://blog.csdn.net/baidu_27414099","[email protected]");
        return new ApiInfo(
                "Swagger Document",
                "Document For Swagger Demo",
                "v1.0",
                "https://blog.csdn.net/baidu_27414099",
                contact,
                "Apache 2.0",
                "http://www/apache.org/icenses/LICENSE-2.0",
                new ArrayList()
        );
    }

}

重启项目，再次在浏览器中访问，相关位置的修改已被修改

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

1.2 Swagger 相关配置

1.2.1 配置是否启动Swagger

在SwaggerConfig 类中可以配置是否启动Swagger

/**
 * 配置Swagger 的 Docket 的 Bean 实例
 * @return
 */
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false); //配置是否启动Swagger
}

enable：false，则不启动Swagger，无法再浏览器中访问

true，则启动Swagger

配置完成，再次启动后在浏览器访问则会出现以下界面

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

1.2.2 配置Swagger 扫描接口

/**
 * 配置Swagger 的 Docket 的 Bean 实例
 * @return
 */
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
            //.paths()
            .build();
}

RequestHandlerSelectors

：配置要扫描的接口，有如下选项：

RequestHandlerSelectors.basePackage() ：基于某一个包扫描，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
            .build();
}

配置后再次启动并访问，则出现以下界面，只有配置扫描的包下的接口会出现在界面中

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

RequestHandlerSelectors.withClassAnnotation()

：扫描类上的注解，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .build();
}

上面的配置就只会扫描有RestController的类

RequestHandlerSelectors.withMethodAnnotation() ：扫描方法上的注解，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
            .build();
}

上面的配置就只会扫描有GetMapping的方法

RequestHandlerSelectors.any() ：扫描全部，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.all())
            .build();
}

RequestHandlerSelectors.none() ：都不扫描，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要扫描的接口
            .apis(RequestHandlerSelectors.none())
            .build();
}

1.2.3 配置过滤器

Swagger 配置过滤器用paths()，如下示例：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .paths(PathSelectors.ant("/test/**"))
            .build();
}

paths需要一个PathSelectors类型的参数，PathSelectors有如下选择

(PathSelectors.ant("") ：如下表示只扫描并通过带有"/test/"的所有请求

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .paths(PathSelectors.ant("/test/**"))
            .build();
}

PathSelectors.regex() ：表示利用正则表达式进行匹配
PathSelectors.any() ：表示所有都通过
PathSelectors.none() ：表示所有都不通过

1.2.4 配置Swagger 文档分组

配置Swagger 用groupName()，如下示例中，配置了多个分组

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("分组1");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("分组2");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("分组3");
    }

    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("分组4");
    }

启动项目并在浏览器中访问Swagger，得到如下界面，可以看到有四个分组可以选择

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

1.3 Swagger 配置 Models

1.3.1 默认配置Models

创建一个实体类UsersModel类如下

public class UsersModel {

    public int id;
    public String name;
    public int age;
    public String sex;
    
}

在TestController类中新增一个方法，用于返回UsersModel示例

@GetMapping(value = "/users")
public UsersModel usersModel(){
    return new UsersModel();
}

启动项目再次访问Swagger文档，如下

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

1.3.2 自定义配置Models

① 给实体类和字段上添加注释，如下

@ApiModel("客户实体类")
public class UsersModel {

    @ApiModelProperty("编号")
    public int id;
    @ApiModelProperty("姓名")
    public String name;
    @ApiModelProperty("年龄")
    public int age;
    @ApiModelProperty("性别")
    public String sex;

}

@ApiModel("客户实体类") ：给实体类添加注释
@ApiModelProperty("编号")
：给实体类的字段添加注释

再次启动并访问，则出现以下界面，可以看大实体类和对应字段都有对应的说明，能够方便查看和使用

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

②给方法添加注释

在方法上添加
@ApiOperation() 即可给该方法添加相应注释，如下示例，在TestController中再添加一个方法

@PostMapping(value = "/test1")
    @ApiOperation("test1方法")
    public String test1(){
        return "tes1";
    }

结果如下

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

给方法参数添加注释

在方法上添加

@ApiParam()

即可给该方法添加相应注释，如下示例，在TestController中再添加一个方法

@PostMapping(value = "/test2")
    @ApiOperation("test2方法")
    public String test2(@ApiParam("str2参数注释")String str2){
        return "test2";
    }

结果如下

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

1.4 Swagger 测试

Swagger 可以利用浏览器直接测试接口，方便调试和查看错误

在Swagger 文档界面，点击

Try it out

，进入到测试界面

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

在测试界面，输入测试参数点击Excecute即可测试

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

测试结果如下，测试结果中包含测试返回信息，以及报错信息

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

SpringBoot 框架（九）—— SpringBoot 集成 Swagger一、SpringBoot 集成 Swagger

SpringBoot 集成 Swagger

一、SpringBoot 集成 Swagger

1.1 创建项目并集成Swagger

1.1.1 创建项目

1.1.2 导入Swgger依赖

1.1.3 编写Config类

1.2 Swagger 相关配置

1.2.1 配置是否启动Swagger

1.2.2 配置Swagger 扫描接口

1.2.3 配置过滤器

1.2.4 配置Swagger 文档分组

1.3 Swagger 配置 Models

1.3.1 默认配置Models

1.3.2 自定义配置Models

1.4 Swagger 测试

继续阅读

关于Gradle配置的小结

Java小案例——随机数猜测随机数猜测

nginx location中斜线的位置的重要性

27 Best Free Eclipse Plug-ins for Java Developer to be ProductiveCode Quality PluginsText Editor PluginsDependency ManagementVersion Control Integration PluginsFramework Development Continuous Integration Related PluginsOther Utility Plugins

Java String.format方法的简单使用

neo4j之cypher使用文档

GitHub连夜封杀！这份阿里 10W 字内部 Java 字面试手册到底有多强？

spark/scala关于【资源文件】加载方法概述外部文件加载方案测试资源文件打包入jar包中小结

mybatis_入门程序Mybatis入门

AOP编程_Android优雅权限框架(1)概念基础，2021金三银四前言正文大纲正文

Effective Java 8:通用程序设计

OOM三种类型

工厂模式-三种类型

【递归】高效率求2的n次幂

win10本地scala和spark安装安装scala安装spark

scala (3) Function 和 Method