Springboot2.x整合Swagger3.x+knife4j3.x

目录

一、SpringBoot添加pom文件依赖

二、创建配置类

 三、接口文档配置

五、APiModel和ApiModelProperty传参对象注解

 六、Swagger3.x响应接口和测试面板

七、离线文档导出

---

一、SpringBoot添加pom文件依赖

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

配置文件增加配置 application.properties

spring.application.name=userService
​
# ===== 自定义swagger配置 ===== #
swagger.enable=true
swagger.application-name= ${spring.application.name}
swagger.application-version=1.0
swagger.application-description=用户接口服务

二、创建配置类

import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Component
@EnableOpenApi
@ConfigurationProperties("swagger")
@Data
public class SwaggerConfiguration{
​
​
    /**
     * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
     */
    private Boolean enable;
​
    /**
     * 项目应用名
     */
    private String applicationName;
​
    /**
     * 项目版本信息
     */
    private String applicationVersion;
​
    /**
     * 项目描述信息
     */
    private String applicationDescription;
​
  
   
     @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .pathMapping("/")
​
                // 定义是否开启swagger，false为关闭，可以通过变量控制，线上关闭
                .enable(enable)
​
                //配置api文档元信息
                .apiInfo(apiInfo())
​
                // 选择哪些接口作为swagger的doc发布
                .select()
​
                //apis() 控制哪些接口暴露给swagger，
                // RequestHandlerSelectors.any() 所有都暴露
                // RequestHandlerSelectors.basePackage("net.iflytek.*")  指定包位置
                // withMethodAnnotation(ApiOperation.class)标记有这个注解 ApiOperation
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
​
                .paths(PathSelectors.any())
​
                .build();
    }
​
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName)
                .description(applicationDescription)
                .contact(new Contact("www.baidu.com", "wwww.baidu.com", "12345678@qq.com"))
                .version(applicationVersion)
                .build();
    }
    
  }
 

 访问连接 端口号根据自己定义的来改：http://localhost:8081/swagger-ui/index.html

 三、接口文档配置

 @Api 模块配置，用在controller类，描述API接口

 @Api(tags = "用户模块",value = "用户UserController")
    public class UserController {
    }

@ApiOperation 接口配置，用在方法上，描述接口方法

   @ApiOperation("分页用户列表")
    @GetMapping("list")
    public JsonData list(){
​
        return JsonData.buildSuccess();
    }

 @ApiParam 方法参数配置，用在入参上面，描述参数

 @ApiOperation("用户登录")
    @PostMapping("login")
    public JsonData login(
            @ApiParam(name = "phone", value = "手机号",example = "13888888888")
            @RequestParam("phone") String phone,
​
            @ApiParam(name = "pwd", value = "密码",example = "123456")
            @RequestParam("pwd")String pwd){
​
        return JsonData.buildSuccess();
    }

@ApiIgnore 忽略此接口不生成文档

  @ApiIgnore
    @ApiOperation("删除用户")
    @DeleteMapping("/delete/{id}")
    public JsonData  deleteById(@PathVariable int id) {
        return JsonData.buildSuccess();
    }

五、APiModel和ApiModelProperty传参对象注解

 @ApiOperation("新增用户")
    @PostMapping("save")
    public JsonData save(@RequestBody SaveUserRequest userRequest){

        return JsonData.buildSuccess();
    }

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@ApiModel(value = "新增用户请求模型")
@Data
public class SaveUserRequest {

    @ApiModelProperty(value = "主键")
    private int id;

    @ApiModelProperty(value = "邮箱",required = true,example = "123456789@qq.com")
    private String email;

    @ApiModelProperty(value = "手机号",required = false)
    private String phone;

    private  String name;

}

 

 六、Swagger3.x响应接口和测试面板

@ApiResponse 描述接口响应

    @ApiOperation("用户登录")
    @PostMapping("login")
    @ApiResponses({
            @ApiResponse(responseCode = HttpCodeStatus.REDIRECT, description = "重定向,跳转登录"),
            @ApiResponse(responseCode = "403",description = "没权限"),
    })
    public JsonData login(
            @ApiParam(name = "phone", value = "手机号",example = "13888888888")

            @RequestParam("phone") String phone,

            @ApiParam(name = "pwd", value = "密码",example = "123456")
            @RequestParam("pwd")String pwd){

        return JsonData.buildSuccess();
    }

 

接口测试： 接口测试调用一般都使用postman swagger用的不多

点击try it out .然后再填入对应参数 点击Execute执行即可 

 使用过程注意事项：

明确接口的Http请求方式 一个接口使用@RequestMapping会生成多个文档

 

@ApiOperation("轮播列表")
@RequestMapping("list")
public JsonData list(){

    List<BannerDO> list = bannerService.list();

    return JsonData.buildSuccess(list);
}

所以，要使用明确接口的Http请求方式。@PostMapping,@GetMapping,@DeleteMapping

七、离线文档导出

Swagger为我们提供了方便的在线文档支持，但某些场景下我们需要把接口文档提供给合作人员，而不是直接给一个地址。此时，我们就需要将接口文档导出为离线文档。

这里集成增强文档knife4j来实现离线文档的导出。

在pom.xml中增加knife4j的依赖：

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

在上面配置Swagger的Swagger3Config中添加@EnableKnife4j注解，该注解可以开启knife4j的增强功能。

访问地址: http://localhost:8081/doc.html。

 此时启动项目，访问doc.html之后，你会发现现在文档风格变得非常酷炫

离线文档下载地址：

 下载下来的文档：