spring boot集成swagger3

maven依赖

        <knife4j-spring-boot-starter.version>3.0.3</knife4j-spring-boot-starter.version>
        <springfox-boot-starter.version>3.0.0</springfox-boot-starter.version>
       
        <!--swagger相关依赖 - 开始-->
        <!--Knife4j增强，根据个人喜好决定是否增加-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>${knife4j-spring-boot-starter.version}</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>${springfox-boot-starter.version}</version>
        </dependency>
        <!--swagger相关依赖 - 结束-->

springfox-boot-starter3.0.0已经将springfox-swagger2、springfox-swagger-ui集成在里面

swagger配置

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.hikvision.starfish.core.util.IpUtils;
import io.swagger.annotations.ApiOperation;
import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
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.net.InetAddress;
import java.util.ArrayList;
import java.util.List;

/**
 * className SwaggerConfig
 * description SwaggerConfig
 *
 * @author 余业宏
 * @date 2021年06月06日 17:35:07
 * @version 1.0
 * @since 1.8
 */
@Slf4j
@Configuration
@EnableOpenApi
//Knife4j增强
@EnableKnife4j
public class SwaggerConfig {

    @Value("${server.port}")
    private int port;
    @Value("${server.servlet.context-path:}")
    private String contextPath;

    @Bean
    @SneakyThrows
    public Docket createApi() {
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .globalRequestParameters(getGlobalRequestParameters())
                // 设置自定义返回消息体
                .globalResponses(HttpMethod.GET, globalResponse())
                .globalResponses(HttpMethod.POST, globalResponse())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .groupName("情指勤舆 - 一号作战部");
        String ipAddress = IpUtils.getLocalIP();
        // 控制台输出Knife4j增强接口文档地址
        log.info("swagger接口文档地址:http://{}:{}{}/swagger-ui/index.html#/", ipAddress, port, contextPath);
        log.info("Knife4j增强接口文档地址: http://{}:{}{}/doc.html", ipAddress, port, contextPath);
        InetAddress inetAddress = InetAddress.getLocalHost();
        String hostName = inetAddress.getHostName();
        log.info("Knife4j增强接口文档地址《计算机名称》: http://{}:{}{}/doc.html", hostName, port, contextPath);
        return docket;
    }

    /**
     * 功能描述: API接口说明
     * @author 余业宏
     * @date 2022年04月22日 08:50:08
     *
     * @return springfox.documentation.service.ApiInfo
     **/
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX项目")
                .description("1.0.0001版本【接口文档接口】")
                .termsOfServiceUrl("https://commandfight/api")
                .contact(new Contact("余业宏/yuyehong", "xxxxx", "xxx"))
                .version("1.0.0001")
                .build();
    }


    /**
     * 功能描述: 生成全局通用参数
     * @author 余业宏
     * @date 2022年04月22日 08:56:26
     *
     * @return java.util.List<springfox.documentation.service.RequestParameter>
     **/
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();

        //设置请求头
        parameters.add(new RequestParameterBuilder()
                .name("user_code")
                .description("当前登录用户编码【开发自测时使用】")
                .required(false)
                .in(ParameterType.HEADER)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }

    /**
     * 功能描述: globalResponse
     * @author 余业宏
     * @date 2022年04月12日 11:43:20
     *
     * @return java.util.List<springfox.documentation.service.Response>
     **/
    private List<Response> globalResponse() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("400").description("错误请求").build());
        responseList.add(new ResponseBuilder().code("401").description("未认证").build());
        responseList.add(new ResponseBuilder().code("403").description("请求被禁止").build());
        responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
        responseList.add(new ResponseBuilder().code("500").description("服务器内部错误").build());
        return responseList;
    }
}

 常用注解

使用示例

/**
     * 功能描述:swagger-get请求参数接口 示例
     * @author 余业宏
     * @date 2022年04月04日 02:16:34
     *
     * @param name        name
     * @param pageIndex pageIndex
     * @param pageSize pageSize
     * @return BaseResponse<Object>
     **/
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "姓名", dataType = "string", defaultValue = "张三", required = false),
            @ApiImplicitParam(name = "pageIndex", value = "页码", dataType = "int", defaultValue = "1", required = false),
            @ApiImplicitParam(name = "pageSize", value = "每页数量", dataType = "int", defaultValue = "10", required = false)
    })
    @ApiOperation(value = "swagger-get请求参数接口", notes = "支持多条件查询", httpMethod = "GET")
    @GetMapping(value = "/swagger-get-api-multi-param")
    public BaseResponse<Object> api1(@RequestParam(defaultValue = "0", required = false) int name,
                                     @RequestParam(defaultValue = "1", required = false) int pageIndex,
                                     @RequestParam(defaultValue = "10", required = false) int pageSize) {
        return BaseResponseBuilder.createResponse();
    }