介绍一下 SpringFox：

Automated JSON API documentation for API's built with Spring

翻译：使用 Spring 构建的 API 的自动化 JSON API 文档

代码

maven 依赖项目 注意Boot项目版本是2.5.13

    <!--声明依赖版本-->
    <properties>
        <swagger.version>3.0.0</swagger.version>
        <knife4f.version>3.0.3</knife4f.version>
    </properties>
    <dependencies>
        <!-- swagger2 可以通过  项目名称+/swagger-ui.html 访问具体页面-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- API获取的包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- 官方UI包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>${knife4f.version}</version>
        </dependency>
    </dependencies>

配置类

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
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;

/**
 * @Author: zanglikun
 * @Date: 2022/3/1 15:48
 * @Description: 新版本的Swagger3 接口文档地址变为 http://127.0.0.1/swagger-ui/index.html 而不是swagger-ui.html
 */

@Configuration
@EnableOpenApi
@EnableKnife4j
@Slf4j
public class NewSwagger {

    @Bean
    public Docket createRestApi() {
        log.info("开始加载Swagger...");
        return new Docket(DocumentationType.OAS_30)
                .enable(true)
                .apiInfo(apiInfo())
                .select()
                .apis( RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //这里是自动匹配注解以显示接口文档
                //.apis(RequestHandlerSelectors.basePackage("com.xunliao")) //这里是指定包来显示其下带有注解的接口文档
//可以选择线上使用某位置 详见 https://www.zanglikun.com/1640.html#@Profile
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("枕聊App新版 接口文档")//标题
                .description("更多请咨询服务开发者，反馈前：请检查ip、端口、接口名是否有效")//描述
                //附加信息
                .contact(new Contact("Java开发团队", "https://www.zanglikun.com", "no@email.com"))
                .version("1.0")//版本
                .build();
    }

}

配置完成之后 即可访问

注意：swagger3 对比 swagger2

接口文档地址变为 http://127.0.0.1/swagger-ui/index.html 而不是2.0的swagger-ui.html

其他问题

Swagger升级到3.x后，原来的MultipartFile在文档调试中，没有此字段了，所以需要我们在字段上追加注解 @RequestPart("")

    public Results doUpUserAvatar(String account,@RequestPart("multipartFile") MultipartFile multipartFile) {
        return infoService.doUpUserAvatar(account, multipartFile);
    }

注意：Swagger3.0提供了新的注解

即便引入3.0是否可以使用2.0注解有待考证