Swagger与Knife4j基本使用方法【SpringBoot】

1.Swagger与Knife4j本地访问方式：

swagger 接口文档默认地址：http://localhost:8080/swagger-ui.html#

Knife4j 接口文档默认地址：http://127.0.0.1:8080/doc.html

2.Swagger的作用？

调试接口，自动生成接口文档

3.Swagger使用流程

3.1 给springboot项目添加依赖

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

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

 3.2 创建Swagger配置文件

@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
@EnableKnife4j  // 开启 Knife4j
@Slf4j
public class SwaggerConfig {
    
    @Bean
    public Docket api(Environment environment) {
        // 设置环境范围
        Profiles profiles = Profiles.of("dev", "test");
        // 如果在该环境返回内则返回：true，反之返回 false
        boolean flag = environment.acceptsProfiles(profiles);
        log.info("flag信息:{}",flag);
        return new Docket(DocumentationType.SWAGGER_2)
              //.host("http://localhost:8080/pre/")
                .groupName("软件部小组")
                .select()   // 设置扫描接口
                .apis(RequestHandlerSelectors
                .any()  // 扫描全部的接口，默认
              //.none() // 全部不扫描
              //.basePackage("com.example.swagger2_demo")  // 扫描的包路径
                )
              //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
              //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
                .paths(PathSelectors.ant("/test/error/**"))// 扫描该路径下的所有接口
                .build().enable(flag).apiInfo(apiInfo());

    }


    @Bean
    public Docket api2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Group 2")
                .select()               
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/test/come/**"))
                .build().enable(true).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("后台管理接口文档")
                .description("后台管理接口文档")
                .version("1.0")
                .build();
    }
}

 

3.3 Swagger常用注解：

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数的描述信息

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParam属性：

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交 仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交 仅支持POST
dataType		参数的数据类型 只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

3.4.实践中，实体类使用Swagger的API范例

package com.example.swagger2_demo.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;

@Getter
@Setter
@ToString
@AllArgsConstructor
@ApiModel("学生")
public class Student {

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("年龄")
    private Integer age;

    @ApiModelProperty("爱好")
    private String hobby;
}

3.5.实践中，Conroller层使用Swagger的API范例

@RestController
@RequestMapping("/test")
@Api("测试")
public class Testcontroller {

    @PostMapping("/getStudent")
    @ApiOperation("获取学生")  //  @ApiOperation 解释该请求的要求
    @ApiImplicitParam(name = "student", value = "频道请求对象", required = true, dataType = "Student")
    public Student getStudent(@RequestBody Student student) {
        System.out.println(student);
        return new Student("小坤",12,"打篮球");
    }

    
}