快捷導(dǎo)航

springboot整合swagger3和knife4j的詳細(xì)過程

更新時間：2022年11月11日 08:59:59 作者：迷失的小鹿

knife4j的前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一樣小巧,輕量,并且功能強(qiáng)悍,下面這篇文章主要介紹了springboot整合swagger3和knife4j的詳細(xì)過程,需要的朋友可以參考下

依賴

 <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
</dependency>

application.yml配置

  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher ## 解決Failed to start bean ‘documentationPluginsBootstrapper‘ 問題
knife4j:
  enable: true

swagger配置類

package com.example.springbooth2.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

@Configuration
@EnableOpenApi//Swagger 開啟生成接口文檔功能
public class SwaggerConfig {

    /**
     * ture 啟用Swagger3.0， false 禁用
     */
    @Value("${knife4j.enable}")
    private Boolean enable;

    @Bean
    Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                //配置網(wǎng)站的基本信息
                .apiInfo(apiInfo())
                .enable(enable)
                .select()
                //指定接口的位置
                // RequestHandlerSelectors.basePackage("com.example.springbooth2.controller") 接口的包所在路徑
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 指定路徑處理PathSelectors.any()代表所有的路徑
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger3") //接口文檔標(biāo)題
                .description("接口文檔") //接口文檔描述
                //作者信息
                // new Contact("作者","作者URL","作者Email")
                .contact(new Contact("jane", "http://www.baidu.com", "123@qq.com"))
                .version("1.0")//版本
                .build();
    }
}

controller

package com.example.springbooth2.controller;

import com.example.springbooth2.config.ResponseResult;
import com.example.springbooth2.entity.User;
import com.example.springbooth2.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;

@Api(tags = "用戶管理接口")
@RestController
@RequestMapping("/user")
public class UserController {

    @Resource
    private UserService userService;

    @ApiOperation("添加用戶")
    @ApiImplicitParams({ // 參數(shù)名稱
            @ApiImplicitParam(name = "userId", value = "用戶id"),
            @ApiImplicitParam(name = "userName", value = "用戶名",  required = true)
    })
    @PostMapping("add")
    public User add(User user) {
        userService.addUser(user);
        return user;
    }

    @ApiOperation("查詢所有用戶")
    @GetMapping("list")
    public ResponseResult<User> list() {
        return ResponseResult.success(userService.list());
    }

    @GetMapping("/findOne")
    public ResponseResult<User> findOne() {
        return ResponseResult.success(userService.findById(1));
    }
}

測試

knife4j訪問地址 http://localhost:9090/doc.html

swagger訪問地址 http://localhost:9090/swagger-ui/index.html

swagger常用注解說明

@Api

用在請求的類上

@Api(tags = “該類的作用進(jìn)行說明”)

@ApiOperation

@ApiOperation(value=“改方法的作用”,note=“備注”)

@ApiImplicitParams

@ApiImplicitParams：用在請求的方法上，表示一組參數(shù)說明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數(shù)的各個方面

name：參數(shù)名
value：參數(shù)的漢字說明、解釋
required：參數(shù)是否必須傳
paramType：參數(shù)放在哪個地方
· header --> 請求參數(shù)的獲?。篅RequestHeader
· query --> 請求參數(shù)的獲取：@RequestParam
· path（用于restful接口）–> 請求參數(shù)的獲?。篅PathVariable
dataType：參數(shù)類型，默認(rèn)String，其它值dataType=“Integer”
defaultValue：參數(shù)的默認(rèn)值

多個 @ApiImplicitParam 注解需要放在一個 @ApiImplicitParams 注解中

@ApiImplicitParam 注解中雖然可以指定參數(shù)是必填的，但是卻不能代替 @RequestParam(required = true) ，

前者的必填只是在 Swagger 框架內(nèi)必填，拋棄了 Swagger ，這個限制就沒用了，所以假如開發(fā)者需要指定一個參數(shù)必填， @RequestParam(required = true) 注解還是不能省略。

@ApiModel

如果參數(shù)是一個對象（例如上文的更新接口），對于參數(shù)的描述也可以放在實體類中。例如下面一段代碼
@ApiModelProperty：用在屬性上，描述類的屬性

@ApiModel(value = "用戶對象",description = "用戶表")
public class User {
    @Id
    @ApiModelProperty(value = "id",required = true)
    private int userId;
    @ApiModelProperty(value = "用戶名稱",required = true)
    private String userName;
}