Swagger的详细讲解及使用

Swagger

官网：API Documentation & Design Tools for Teams | Swagger

前后端分离：

• 前端测试后端接口：postman
• 后端提供接口

api框架：

• RestFul API文档在线自动生成工具—api文档与api定义同步更新
• 直接运行，可以在线测试api接口

在项目中使用swagger需要springbox：

• swagger2
• ui

springBoot集成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>

配置swagger：

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
}

产生的问题：Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException

因为版本不兼容

解决：

• 在springboot的配置文件中配置如下：因为高版本后的路径匹配修改了

• spring:
    mvc:
      pathmatch:
        matching-strategy: ant_path_matcher
  

• 降低springboot版本到2.5.6

测试运行：Swagger UI

配置swagger

• Swagger的bean实例 Docket

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

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("liuxiang", "http://localhost:8080/", "971223772@qq.com");
        return new ApiInfo("刘想的swagger日记",
                "牛牛的Java学习之旅",
                "1.0",
                "http://localhost:8080/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

Swagger配置扫描接口

 @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation()：扫描类上的注解
                //withMethodAnnotation():扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.liu.swagger.controller"))
                //paths():过滤路径
                .paths(PathSelectors.ant("/liu/**"))
                .build();
    }

配置是否启动swagger

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false) //是否启动swagger
            .select()
          .apis(RequestHandlerSelectors.basePackage("com.liu.swagger.controller"))
            .build();
}

测试题

如果想要在生产环境下开启swagger，在测试环境下不开启

方法：

• 通过设置两套模式application-dev.properties和application-prod.properties,分别配置不同的端口号，在application.properties中选择开启哪套环境

• spring.profiles.active=dev
  

• 在swaggerConfig中配置：

• @Bean
  public Docket docket(Environment environment){
  
  //设置要显示的swagger环境
  Profiles profiles = Profiles.of("dev", "test");
  //通过environment.acceptsProfiles判断是否处在设定的环境下
  boolean flag = environment.acceptsProfiles(profiles);
  
  return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .enable(flag)
          .select()
          .apis(RequestHandlerSelectors.basePackage("com.liu.swagger.controller"))
          .build();
  }
  

配置API文档分组

配置多个分组，多个Docket即可！

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("B"); }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

实体类配置

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

}

controller

//只要接口中的返回值存在实体类，就会被扫描到swagger中
@PostMapping(value = "/user")
    public User user(){
        return new User();
    }

其他的注解

@ApiOperation("hello控制类") //用在方法上
    @GetMapping(value = "/hello")
    public String hello(@ApiParam("用户名") String username){
        return "hello"+username;
    }

结果：有中文了

}

其他的注解

```java
@ApiOperation("hello控制类") //用在方法上
    @GetMapping(value = "/hello")
    public String hello(@ApiParam("用户名") String username){
        return "hello"+username;
    }

结果：有中文了