springboot2.0 集成swagger3+Knife4j导出离线API 配置

springboot 版本2.3.1

一、集成swagger3

1. 引入swagger依赖包

        <!--swagger3集成-->
        <dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-core</artifactId>
            <version>2.0.0.RELEASE</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-metadata</artifactId>
            <version>2.0.0.RELEASE</version>
            <exclusions>
                <exclusion>
                    <artifactId>spring-plugin-core</artifactId>
                    <groupId>org.springframework.plugin</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework.plugin</groupId>
                    <artifactId>spring-plugin-core</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework.plugin</groupId>
                    <artifactId>spring-plugin-metadata</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

开启 swagger-ui.html的图形化界面开关

springfox:
  documentation:
    swagger-ui:
      enabled: true

3. 增加swager3 配置类和文档配置说明

mport io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;


@Configuration
@EnableOpenApi
public class Swagger3Config {

    @Bean
    public Docket createRestApi(){
        //返回文档概要信息
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET,getGlobalResponseMessage())
                .globalResponses(HttpMethod.POST,getGlobalResponseMessage());
    }

    /*
    生成接口信息，包括标题，联系人等
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("组件接口文档")
                .version("1.0")
                .build();
    }


    /*
    封装全局通用参数
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters=new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("uuid")
                .description("设备uuid")
                .required(true)
                .in(ParameterType.QUERY)
                .query(q->q.model(m->m.scalarModel((ScalarType.STRING))))
                .required(false)
                .build());

        return parameters;
    }

//    封装通用相应信息

    private List<Response> getGlobalResponseMessage() {
        List<Response> responseList=new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("未找到资源").build());
        return responseList;
    }
   

4.本地访问地址

本地swagger 文档地址：http://127.0.0.1:10008/swagger-ui/index.html#

二、基于Knife4j导出离线API 配置

Knife4j是一款基于Swagger 2的在线API文档框架，是日常开发中很常用的框架，基于此框架，后端可以和前端开发人员进行高效沟通。

2.1 导入配置pom
添加Knife4j的依赖（当前建议使用的Knife4j版本，只适用于Spring Boot 2.6以下版本，不含Spring Boot 2.6）

   <!--swagger Knife4j导出配置-->

        <!--Knife4j-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>

2.2 开启Knife4j增加注解和swagger导出ui关闭

knife4j:
  enable: true
springfox:
  documentation:
    swagger-ui:
      enabled: false

3 .启用Knife4j 功能
在启动类增加注解@EnableKnife4j ，开启Knife4j 功能

@EnableKnife4j 

4.访问地址
http://127.0.0.1:10008/doc.html