Swagger knife4j

前言

现在都是行前后开发模式，这样开发效率大大提高了，但是这样也会引来一系列的问题，就是前后端开发人员他们在进行交互的时候不能时刻达到统一，这样产生了问题(打架)

swagger

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

我们这里是使用的swagger3.0版本 ，现在直接添加启动器就可以了
pom

  <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

由于swagger默认的UI界面不好看，所以我们这里使用一个第三方的ui bootstart-ui，添加knife4j，他里面集成了bootstart-ui、swagger3.0。

<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>

核心配置

@Configuration
@EnableOpenApi  //开启swagger3.0
@EnableKnife4j		//开启Knife4j
public class SwaggerConfig {
    //分组设置
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.OAS_30)
                .groupName("B组");
    }

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)//选择文档的类型
                .apiInfo(apiInfo())//apiInfo 一些进本信息
                .host("localhost:8080/doc.html")
                .groupName("A组")
                .select()//选择那些接口发布到swagger上
                .apis(RequestHandlerSelectors.basePackage("com.aw.swagger.controller"))//basePackage()指定扫描接口包 any()所有的访问都为true
                .paths(PathSelectors.any())//允许所有路径通过
                .build();

    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("swagger测试")
                .description("swagger说明")
                .termsOfServiceUrl("服务地址")
                .contact(new Contact("阿威","k12code.online","2331890842@qq.com"))
                .license("许可证")
                .licenseUrl("许可证地址")
                .version("1.0版本")
                .build();
    }

}

Controller层的注解

@RestController
@Api(tags = "Demo部门")
@ApiSort(1)//接口排序
public class Demo {
    @ApiOperation(value = "这是一个测试方法")
    @ApiOperationSupport(order = 1,author = "阿威")
    @ApiImplicitParam(name = "name",value = "张三",required = true,dataType = "String",defaultValue = "张三")
    @GetMapping("/hello")
   public String test(String name){
        return "hello";
    }
    @ApiOperation("获取所有的用户")
    @PostMapping("/getUser")
    public User getUser(@RequestBody User user){
        return user;
    }
}

Model层注解

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户实体类")
public class User{
    @Id
    @ApiModelProperty(value = "主键")
    private String id;
    private String name;
    private Integer age;
}

启动服务，访问http://localhost:端口号/doc.html
就能看到这样的界面

由于我们在开发中有测试版本、还有生产版本，我们生产版本中就不需要开启swagger。
application.yml

spring:
  profiles:
    active: dev

application-dev.yml

server:
  port: 8081
knife4j:
  # 开启增强配置
  enable: true
  # 开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    # Basic认证用户名
    username: test
    # Basic认证密码
    password: 123

application-pro.yml

server:
  port: 8082
knife4j:
  #开启增强配置
  enable: true
  #开启生产环境屏蔽
  production: true

swagger3.0的注解变化

@ApiParam -> @Parameter
@ApiOperation -> @Operation
@Api -> @Tag
@ApiImplicitParams -> @Parameters
@ApiImplicitParam -> @Parameter
@ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiModel -> @Schema
@ApiModelProperty -> @Schema