spring-boot整合swagger

莫已诺2024-04-032024-04-11

Spring Boot 2.7.3 整合Swagger

maven 引入 Swagger包

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
    <exclusions>
        <exclusion>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
        </exclusion>
        <exclusion>
            <artifactId>swagger-models</artifactId>
            <groupId>io.swagger</groupId>
        </exclusion>
        <exclusion>
            <groupId>org.javassist</groupId>
            <artifactId>javassist</artifactId>
        </exclusion>
    </exclusions>
</dependency>

添加 SwaggerConfig 配置类：

import org.springframework.boot.actuate.autoconfigure.endpoint.web.CorsEndpointProperties;
import org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties;
import org.springframework.boot.actuate.autoconfigure.web.server.ManagementPortType;
import org.springframework.boot.actuate.endpoint.ExposableEndpoint;
import org.springframework.boot.actuate.endpoint.web.*;
import org.springframework.boot.actuate.endpoint.web.annotation.ControllerEndpointsSupplier;
import org.springframework.boot.actuate.endpoint.web.annotation.ServletEndpointsSupplier;
import org.springframework.boot.actuate.endpoint.web.servlet.WebMvcEndpointHandlerMapping;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.web.bind.annotation.RestController;
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;

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

@EnableOpenApi
@Configuration
public class SwaggerConfig {
    /**
     * 配置基本信息
     * @return
     */
    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX系统管理api接口文档")
                .description("XX系统管理api接口文档")
                .termsOfServiceUrl("https://localhost:8080")
                .contact(new Contact("Z","https://zerocc.top","xxx@csdn.net"))
                .version("1.0")
                .build();
    }

    /**
     * 配置文档生成最佳实践
     * @param apiInfo
     * @return
     */
    @Bean
    public Docket createRestApi(ApiInfo apiInfo) {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo)
                .groupName("SwaggerGroupOneAPI")
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 增加如下配置可解决Spring Boot  与Swagger 3.0.0 不兼容问题
     **/
    @Bean
    public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier, ServletEndpointsSupplier servletEndpointsSupplier, ControllerEndpointsSupplier controllerEndpointsSupplier, EndpointMediaTypes endpointMediaTypes, CorsEndpointProperties corsProperties, WebEndpointProperties webEndpointProperties, Environment environment) {
        List<ExposableEndpoint<?>> allEndpoints = new ArrayList();
        Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
        allEndpoints.addAll(webEndpoints);
        allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
        allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());
        String basePath = webEndpointProperties.getBasePath();
        EndpointMapping endpointMapping = new EndpointMapping(basePath);
        boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);
        return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(), new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping, null);
    }
    private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) {
        return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));
    }
}

StringUtils 中的hasText

public static boolean hasText(String str) {
    return str != null && !str.isEmpty() && containsText(str);
}

private static boolean containsText(CharSequence str) {
    int strLen = str.length();

    for(int i = 0; i < strLen; ++i) {
        if (!Character.isWhitespace(str.charAt(i))) {
            return true;
        }
    }

    return false;
}

正常启动工程后访问

swagger的传统页面

http://localhost:15666/swagger-ui/index.html

基于knife4j-spring-boot-starter 优化ui 体验并且可以导出离线文档

http://localhost:15666/doc.html

部分写法及例子

@ApiModel 和 @ApiModelProperty

@ApiModel(description = “”) ：用在 JavaBean 类上，说明 JavaBean 的用途
@ApiModelProperty(value = “”) ：用在 JavaBean 类的属性上面，说明此属性的的含义

@ApiModel(description = "用户表")
public class UserEntity implements Serializable {
    @ApiModelProperty(value = "主键ID")
    private Long id;
    ...
}

@Api

@Api(tags = “”)：用在请求的类上，表示对类的说明
1、tags=“说明该类的作用，可以在UI界面上看到的注解”
2、value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”`（不需要配置）

@Api(tags = "标签管理系统")
@Slf4j
@RestController
@RequestMapping("/tags-web")
public class TagsWebController {}

@ApiOperationSupport 和 @ApiOperation

@ApiOperationSupport(author = “”) 相当于接口作者
@ApiOperation(“”) 相当于是 @ApiOperation(value = “”)
@ApiOperation：用在请求的方法上，说明方法的用途、作用
1、value=“说明方法的用途、作用”
2、notes=”方法的备注说明（看情况，一般不需要配置）
例子: @ApiOperation(value=“用户注册”,notes=“用户名和密码是必填项，年龄随便填，但必须是数字”)

@ApiOperation(value = "新增一级或二级标签",notes = "一二级标签只记录级别和名称即可")
@PostMapping("/tags/add-one-two")
public R addData(@RequestBody List<TagDto> tags) {
    if (tags == null) {
        return R.fail("标签集合不能为空");
    }
    return tagService.addTag(tags);
}

@ApiImplicitParam 和 @ApiImplicitParams

@ApilmplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面

name：参数名（必须）
value：参数的汉字说明、解释（必须）
required：参数是否必须传，默认false（如果可不传也可以不写）
paramType：参数放在哪个地方，查询参数类型，这里有几种形式（实体/数组/集合必须写，非左边三种可写可不写）

header（非常少用）→ 请求参数的获取：@RequestHeader，参数在 request headers（请求头）里边提交

query（常用）→ 请求参数的获取：@RequestParam，用于 get 请求的参数拼接，直接跟参数，完成自动映射赋值

path（一般）→ 请求参数的获取：@PathVariable，以地址的形式提交数据

body（常用）→ 请求参数的获取：@RequestBody，以流的形式提交仅支持 POST

@ApiOperation(value = "标签查询")
@ApiImplicitParams({
        @ApiImplicitParam(name = "state", value = "标签状态", dataType = "String",paramType = "query"),
        @ApiImplicitParam(name = "level", value = "标签等级", dataType = "String" ,paramType = "query"),
        @ApiImplicitParam(name = "pid", value = "上级标签id", dataType = "Integer",paramType = "query")
})
@GetMapping("/tags")
public R listData(@ApiIgnore @RequestParam Map<String, Object> params) {
    return tagService.listData(params);
}