当前位置：首页 > article >正文

SpringBoot3集成Swagger接口文档功能、接口排序以及如何设置接口页面的title/keyword/description?

article 2025/1/2 3:11:14

一、SpringBoot3集成Swagger接口文档功能

在SpringBoot3 中集成 Swagger 接口文档，如果按照网上的很多提示，会有些问题。在这个过程中我就遇到报错：

Caused by: java.lang.ClassNotFoundException: javax.servlet.http.HttpServletRequest

因为最新的 SpringBoot3 里javax命令空间有变化，而 Swagger 已经停更。经过调试我这边成功的配置和示例如下：

1. 引入的包为 springdoc-openapi-starter-webmvc-ui

之前测试一些常用的 swagger-annotations

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

2. application.yaml中的相关配置

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    groups-order: desc

3. Swagger3中的 SwaggerConfig 类如下

package cn.fangha.config;

import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI springOpenAPI() {
        return new OpenAPI().info(
            new Info().title("信息API接口")
                    .description("本接口。。。。")
                    .version("1.0.0")
                    .summary("summary.")

        );
    }

}

4. Swagger3 中使用的注解

Swagger2 和 Swagger3 使用注解区别很大，基本完全变了。

Swagger2                    Swagger3
@Api                            @Tag
@ApiOperation            @Operation
@ApiImplicitParams   @Parameters
@ApiImplicitParam      @Parameter
@ApiModel                  @Schema
@ApiModelProperty @Schema
@ApiResponses @ApiResponses
@ApiResponse            @ApiResponse
@ApiIgnore                  @Hidden

主要使用的也就是 Tag 和 Parameter 注解。放在 controller的方法上标识接口。如下为我一个测试控制器的方法如下：

5. 业务控制器中的方法注解如下：

此处只用于测试，接口方法均先返回的 Listmap数据。尚未使用 json 包处理。示例如下：

package cn.fangha.controller;

import cn.fangha.services.NormalService;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

@RestController
@Tag(name="API接口大全")
public class LineController {

    @Autowired
    private NormalService normalService;


    @ApiResponse(description = "线路详情")
    @Parameter(name = "keychar", description = "线路", required = true)
    @GetMapping("/detail/{keychar}")
    public Map<String, Object> gaotie_detail(@PathVariable("keychar") String keychar){

        Map<String, Object> map = normalService.get_detail(keychar);

        return map;
    }

}

二、Swagger3中的接口排序以及如何设置接口页面的title/keyword/description?

如上，SpringBoot3 集成的 Swagger3 接口文档实际上是用的 springdoc-openapi-starter-webmvc-ui , 网上很多集成 swagger 的多是 Springfox 的，因此没法参考使用。通过上面的这些配置处理，展示的页面效果如下：

在使用 springdoc-openapi-starter-webmvc-ui 的时候，发现有二个问题未实现。

一是实现的对接口的排序，在 Swagger2 里有一个 order 链式方法可以使用，但在这里我试了试，只发现在springdoc yaml 配置中有一个 writer-with-order-by-keys 。其值有 true/false/on/off ,尝试了一下都不能达到的我预期。设置为true/false 其会按字母倒序、顺序展示，但一不能实现直接按控制器中的接口方法顺序排列，也未看到哪里有自定义的顺序参数。

二是对于接口页面其页面的 title/description/keywords 未找到哪里可以进行设置。有些在yml配置中追加开启了 Knife4j 增强，但我对于目前的 Swagger 其它都满意，就只有这两个点没有找到方法。如果有朋友发现了这两个问题的解决方法，欢迎在评论中告诉我，感谢！

查看全文

http://www.kler.cn/a/374305.html