Swagger2_new docket().pathmaping-CSDN博客

本文链接：https://blog.csdn.net/bing_bg/article/details/118306075

Swagger简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

接口的文档在线自动生成。
功能测试。

Spring boot集成Swagger

新建一个springboot项目

添加Maven依赖

<!--Swagger2依赖 -->
<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>

编写一个HelloWord工程

@RestController
public class HelloController {
    @GetMapping("/Hello")
    public String sayHello(){
        return "Hello";
    }
}

配置Swagger,编写配置类

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

注意：这里直接使用默认值测试

重启项目，访问 http://localhost:8080/swagger-ui.html

Swagger详细配置

配置基本信息

private ApiInfo apiInfo() {
    //作者信息 名字，链接，邮箱
    Contact contact = new Contact("lbb", "https://blog.csdn.net/bing_bg", "lbb@163.com");
    return new ApiInfo("lbb的Api文档", //题目
            "这是最牛逼的项目",  //描述
            "v1.0",  //版本
            "https://blog.csdn.net/bing_bg",  // 组织链接
            contact, // 联系人信息
            "Apache 2.0",  // 许可
            "http://www.apache.org/licenses/LICENSE-2.0", // 许可连接
            new ArrayList());// 扩展
}

配置Swagger的Bean实例

在上面建的配置类中配置Swagger的Bean实例，部分配置如下：

//配置Swagger的Bean实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()// 通过.select()方法，去配置扫描接口,下面 RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.lbb.swagger_demo.controller"))
            .build();
}

RequestHandlerSelectors的方法：

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

接口扫描过滤 paths方法

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.lbb.swagger_demo.controller"))
       
       // 配置如何通过path过滤,即这里只扫描请求以/lbb开头的接口
      .paths(PathSelectors.ant("/lbb/**"))
      .build();
}

PathSelectors的方法：

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

配置Swagger开关 enable方法

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

//配置Swagger的Bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                
                .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问

                .select()// 通过.select()方法，去配置扫描接口,下面 RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.lbb.swagger_demo.controller"))
                // 配置如何通过path过滤,即这里只扫描请求以/lbb开头的接口
                .paths(PathSelectors.ant("/lbb/**"))
                .build();
    }

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

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

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
				//.enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .enable(b) //配置在何种环境下启用Swagger
            
                .select()// 通过.select()方法，去配置扫描接口,下RequestHandlerSelectors配置如何扫描接口             
            .apis(RequestHandlerSelectors.basePackage("com.lbb.swagger_demo.controller"))
                // 配置如何通过path过滤,即这里只扫描请求以/lbb开头的接口
				.paths(PathSelectors.ant("/lbb/**"))
                .build();
    }

配置API分组

没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello"); // 配置分组
}

配置多个分组

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("lbb1"); // 配置分组1
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("lbb2"); // 配置分组2
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("lbb3"); // 配置分组3
}

实体配置

新建一个实体类
```
@ApiModel("用户实体")
public class User {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}
```
注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。其中 @ApiModel为类添加注释，@ApiModelProperty为类属性添加注释。
实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：
```
@GetMapping("/getUser")
public User getUser(){
   return new User();
}
```
重启查看测试

常用注解

Swagger的所有注解定义在io.swagger.annotations包下,常用注解如下:

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

可以给请求的接口配置一些注释

@ApiOperation("lbb的接口")
@PostMapping("/lbb")
@ResponseBody
public String lbb(@ApiParam("这个名字会被返回")String username){
   return username;
}

运行查看即可！

皮肤扩展

默认的，访问 http://localhost:8080/swagger-ui.html

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

knife4j 访问http://localhost:8080/doc.html

<!-- 引入knife4j包 /doc.html-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>2.0.4</version>
</dependency>

mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>