Swagger系列：SpringBoot3.x中使用Knife4j

一、簡介

官網：https://doc.xiaominfo.com/

Knife4j是一個集Swagger2 和 OpenAPI3 為一體的增強解決方案

Knife4j 是為 Java MVC 框架整合 Swagger 生成 Api 檔案的增強解決方案，前身是 swagger-bootstrap-ui，致力於 springfox-swagger 的增強 UI 實現。knife4j 為了契合微服務的架構發展，由於原來 swagger-bootstrap-ui 採用的是後端 Java 程式碼 + 前端 UI 混合打包的方式，在微服務架構下顯的很臃腫，因此專案正式更名為 knife4j，更名後主要專注的方面如下：

• 後端 Java 程式碼以及前端 UI 模組進行了分離，在微服務架構下使用更加靈活
• 提供專注於 Swagger 的增強解決方案，不同於只是單純增強前端 UI 部分

二、版本說明

Spring Boot版本相容性

Swagger2規範和OpenAPI3規範的說明

三、使用

1.引入依賴

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

2.編寫設定類

package com.mcode.knife4jdemo.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * ClassName: Knife4jConfig
 * Package: com.mcode.knife4jdemo.config
 * Description:
 *
 * @Author: robin
 * @Version: v1.0
 */
@Configuration
public class Knife4jConfig {
    @Bean
    public GroupedOpenApi adminApi() {      // 建立了一個api介面的分組
        return GroupedOpenApi.builder()
                .group("admin-api")         // 分組名稱
                .pathsToMatch("/admin/**")  // 介面請求路徑規則
                .build();
    }
    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(new Info()
                        .title("Knife4j標題")
                        .description("Knife4j說明")
                        .version("v1")
                        .contact(new Contact().name("robin").email("[email protected]"))
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                );

    }
}

3.編寫User類用作模型

package com.mcode.knife4jdemo.entity;

import io.swagger.v3.oas.annotations.media.Schema;

/**
 * ClassName: User
 * Package: com.mcode.knife4jdemo.entity
 * Description:
 *
 * @Author: robin
 * @Version: v1.0
 */
@Schema(description = "使用者實體")
public class User {
    @Schema(description = "使用者名稱稱")
    private String userName;
    @Schema(description = "密碼")
    private String password;
    @Schema(description = "郵箱")
    private String email;

    @Schema(description = "年齡")
    private int age;


    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public User() {
    }

    public User(String userName, String password, String email, int age) {
        this.userName = userName;
        this.password = password;
        this.email = email;
        this.age = age;
    }
}

4.編寫控制器

package com.mcode.knife4jdemo.controller;

import com.mcode.knife4jdemo.entity.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

/**
 * ClassName: IndexController
 * Package: com.mcode.knife4jdemo.controller
 * Description:
 *
 * @Author: robin
 * @Version: v1.0
 */
@RestController
@Tag(name = "首頁")
@RequestMapping("/admin/index")
public class IndexController {
    @Operation(summary = "獲取使用者")
    @GetMapping("/getUser")
    public User getUser( @Parameter(name = "userName",description = "使用者名稱稱",in = ParameterIn.QUERY)String userName) {
        return new User(userName, "123456", "[email protected]", 18);
    }
    @Operation(summary = "新增使用者")
    @PostMapping("/addUser")
    public Boolean addUser(@RequestBody  User user) {
        return true;
    }
}

SpringDoc註解具體可看：https://www.cnblogs.com/vic-tory/p/17690501.html

四、效果圖

首頁

控制器