<modelVersion>4.0.0</modelVersion>
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.5.4</version>
</parent>
<groupId>com.example</groupId>
<artifactId>springboot-swagger</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!--引入spring web -->
    <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>
    <!--Knife4j-->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>3.0.2</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <mainClass>com.example.SpringbootSwaggerSampleApplication</mainClass>
            </configuration>
        </plugin>
    </plugins>
</build>

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseBuilder;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Response;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;
/**
 * @Description: (Swagger配置)
 * @Date 2023/09/07
 */
@Configuration
@EnableOpenApi
@EnableKnife4j
public class SwaggerConfig {
    /**
     * swagger3的配置文件
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                //.globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResponseMessage())
                .globalResponses(HttpMethod.DELETE, getGlobalResponseMessage())
                .globalResponses(HttpMethod.PUT, getGlobalResponseMessage());
    }
    /**
     * 構(gòu)建 api文檔的詳細(xì)信息函數(shù),注意這里的注解引用的是哪個(gè)
     */
    private ApiInfo apiInfo() {
        // 獲取工程名稱
        String projectName = System.getProperty("user.dir");
        return new ApiInfoBuilder()
                .title(projectName.substring(projectName.lastIndexOf("\\") + 1) + " API接口文檔")
                .contact(new Contact("coderJim", "https://www.example.com", "coderJim@163.com"))
                .version("1.0")
                .description("API文檔")
                .build();
    }
    /**
     * 生成通用響應(yīng)信息
     *
     * @return
     */
    private List<Response> getGlobalResponseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("找不到資源").build());
        return responseList;
    }
}

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.ToString;
/**
 * @Description: (用一句話描述該文件做什么)
 * @date 2023/09/07
 */
@Data
@ToString
@ApiModel(value = "用戶實(shí)體類", description = "用戶信息描述類")
public class User {
    @ApiModelProperty(value = "用戶id")
    private Integer id;
    @ApiModelProperty(value = "用戶名")
    private String username;
    @ApiModelProperty(value = "用戶密碼")
    private String password;
}

import com.example.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
/**
 *
 * @Package com.example.controller
 * @Description: (用一句話描述該文件做什么)
 * @date 2023/09/07
 */
@RestController
@Api(tags = "用戶數(shù)據(jù)接口") // @Api 注解標(biāo)注在類上用來描述整個(gè) Controller 信息。
public class UserController {
    /**
     * @ApiOperation 注解標(biāo)注在方法上，用來描述一個(gè)方法的基本信息。
     */
    @ApiOperation(value = "修改用戶", notes = "傳入用戶信息進(jìn)行更新修改")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user){
        return user.toString();
    }
    /**
     * @ApiImplicitParam 注解標(biāo)注在方法上，用來描述方法的參數(shù)。其中 paramType 是指方法參數(shù)的類型，有如下可選值：
     * path：參數(shù)獲取方式為 @PathVariable
     * query：參數(shù)獲取方式為 @RequestParam
     * header：參數(shù)獲取方式為 @RequestHeader
     * body
     * form
     */
    @ApiOperation(value ="查詢用戶", notes = "根據(jù) id 查詢用戶")
    @ApiImplicitParam(paramType = "path", name = "id", value = "用戶 id", required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id){
        return "查找的用戶id是：" + id;
    }
    /**
     * 如果有多個(gè)參數(shù)，可以將多個(gè)參數(shù)的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中
     */
    @ApiOperation(value = "新增用戶", notes = "根據(jù)傳入的用戶名和密碼添加一個(gè)新用戶")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "username",
                    value = "用戶名", required = true, defaultValue = "test"),
            @ApiImplicitParam(paramType = "query", name = "password",
                    value = "密碼", required = true, defaultValue = "123")
    })
    @PostMapping("/user")
    public String addUser(@RequestParam String username, @RequestParam String password) {
        return "新增用戶：" + username + " " + password;
    }
    /**
     * @ApiResponse 是對(duì)響應(yīng)結(jié)果的描述。code 表示響應(yīng)碼，message 為相應(yīng)的描述信息。如果有多個(gè) @ApiResponse，則放在一個(gè) @ApiResponses 中
     */
    @ApiOperation(value = "刪除用戶", notes = "根據(jù) id 刪除用戶")
    @ApiResponses({
            @ApiResponse(code = 200, message = "刪除成功！"),
            @ApiResponse(code = 500, message = "刪除失?。?)
    })
    @DeleteMapping("/user/{id}")
    public Integer deleteUserById(@PathVariable Integer id) {
        return id;
    }
    /**
     * @ApiIgnore 注解表示不對(duì)某個(gè)接口生成文檔。
     */
    @ApiIgnore
    @GetMapping("/user/test")
    public String test() {
        return "這是一個(gè)測(cè)試接口，不需要在api文檔中顯示。";
    }
}