1、SpringBoot新增pom檔案依賴

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.11</version>
        <relativePath/>
    </parent>

    <properties>
        <java.version>11
 
</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--swagger3依賴-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0
 
.0</version>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.16</version>
            <scope>provided</scope>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

2、配置檔案增加配置

server:
  port: 8082

spring:
  application:
    name: swagger-server

swagger:
  enable: true
  application-name: ${spring.application.name}
  application-version: 1.0
  application-description: 電商平臺管理後端介面文件

3、建立配置類

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.ApiKey;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

@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.xdclass.*")  指定包位置
                // withMethodAnnotation(ApiOperation.class)標記有這個註解 ApiOperation
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any()).build()
                // 如何保護我們的Api，有三種驗證（ApiKey, BasicAuth, OAuth）
                .securitySchemes(security())
                // 介面文件的基本資訊
                .apiInfo(apiInfo());
    }


    /**
     * 介面文件詳細資訊
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName)
                .description(applicationDescription)
                .contact(new Contact("聯絡標題", "https://www.baidu.com", "[email protected]"))
                .version(applicationVersion)
                .build();
    }

    private List<SecurityScheme> security() {
        ArrayList<SecurityScheme> apiKeys = new ArrayList<>();
        apiKeys.add(new ApiKey("accessToken", "accessToken", "accessToken"));
        return apiKeys;
    }


}

4、建立controller類

import com.example.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@Api(tags = "測試介面")
@RestController
@RequestMapping("demo")
public class DemoController {

    @ApiOperation("查詢集合資料")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "id",value = "查詢id"),
            @ApiImplicitParam(name = "name",value = "查詢名稱",required = true)
    })
    @ApiResponses({
            @ApiResponse(responseCode = "200", description ="OK"),
            @ApiResponse(responseCode = "204", description ="No results returned")
    })
    @PostMapping("list1")
    public List<String> list1(Integer id,String name){
        List<String> list = new ArrayList<>();
        list.add("張三");
        list.add("李四");
        return list;
    }

    @ApiOperation("測試刪除")
    @ApiImplicitParam(name = "id", value = "刪除ID", example = "100", required = true)
    @PostMapping(value = "/delete/{id}")
    public Integer delete(@PathVariable("id") Long id){
        System.out.println("刪除成功："+id);
        return 200;
    }

    @ApiOperation("保持物件")
    @PostMapping("save")
    public Object save(@RequestBody User user){
        User user1 = new User();
        user1.setId(user.getId());
        user1.setName(user.getName());
        return user1;
    }

}

5、訪問http://localhost:8082/swagger-ui/index.html

6、常用註解，官網

-@Api()用於類；
表示標識這個類是swagger的資源

-@ApiOperation()用於方法；
表示一個http請求的操作

-@ApiParam()用於方法，引數，欄位說明；
表示對引數的新增元資料（說明或是否必填等）

-@ApiModel()用於類
表示對類進行說明，用於引數用實體類接收

-@ApiModelProperty()用於方法，欄位
表示對model屬性的說明或者資料操作更改

-@ApiIgnore()用於類，方法，方法引數
表示這個方法或者類被忽略

-@ApiImplicitParam()用於方法
表示單獨的請求引數

-@ApiImplicitParams()用於方法，包含多個 @ApiImplicitParam

具體使用舉例說明：

@Api()
用於類；表示標識這個類是swagger的資源
tags–表示說明
value–也是說明，可以使用tags替代