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

一、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-docsswagger-ui:path: /swagger-ui.htmlgroups-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 {@Beanpublic 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 {@Autowiredprivate 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 其它都满意，就只有这两个点没有找到方法。如果有朋友发现了这两个问题的解决方法，欢迎在评论中告诉我，感谢！