使用springdoc-openapi这个库来生成swagger的api文档

官方Github仓库： https://github.com/springdoc/springdoc-openapi

官网地址：https://springdoc.org

1. 引入依赖

目前最新的版本是 springdoc-openapi v2.6.0。

然而 springdoc-openapi v1.8.0 是支持 Spring Boot 2.x 和 1.x 的最新开源版本。

而我的项目用的是 springboot 2.2.1 ，于是我就选择 1.8.0 的版本。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>

大伙如果用的是 springboot 3 ，可以尝试使用最新版本的。

注意：SpringDoc不兼容swagger2的注解

2. 拦截器设置

如果项目中使用到了拦截器，那么就无法访问 http://localhost:8080/swagger-ui.html（端口号自行修改）

需要到 WebConfigurer 的 addInterceptors 方法中，排除swagger的路径

.excludePathPatterns("/swagger**/**","/**/api-docs/**")

或者这种写法

.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/**/api-docs/**")

案例：

	// 自定义拦截器JwtInterceptor，设置拦截规则
	@Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loginInterceptor)
        	.addPathPatterns("/**")
        	.excludePathPatterns("/login", "/register", "/files/**",
                "/swagger**/**","/**/api-docs/**");
    }

或者这样写

	// 自定义拦截器JwtInterceptor，设置拦截规则
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(jwtInterceptor)
                .addPathPatterns("/**")

                .excludePathPatterns("/login")
                .excludePathPatterns("/register")
                .excludePathPatterns("/files/**")
                
				// 排除swagger
                .excludePathPatterns("/swagger**/**")
                .excludePathPatterns("/**/api-docs/**")
                ;
    }

3. 访问接口页面

配置好拦截器，重新启动，访问 http://localhost:8080/swagger-ui.html（端口号自行修改）

就可以看到如下画面，代表可以成功使用swagger了。

通过搜索框可以看到，访问路径是被重定向到 http://localhost:8080/v3/api-docs 。

所以排除的路径中，把包含swagger和api-docs的路径都排除了。

3.1 添加配置项，使得访问路径变短（非必须）

此时也可以在application.properties中添加一些配置，具体可以参考Spring Boot 整合 springdoc-openapi中的配置。

只加一行把/swagger-ui.html这个默认路径修改成比较方便访问的路径。

springdoc.swagger-ui.path=/api-docs

这样就变成了可以用 http://localhost:8080/api-docs 较短的路径来访问了。

4. 修改页面显示信息

基本信息注解	描述	可用于	属性
@OpenAPIDefinition	定义整个 API 文档的基本信息	类、接口	info：指定 @Info 注解的对象，用于描述 API 文档的基本信息。
@Info	定义 API 文档的基本信息	类、接口	title：API 的标题。 description：API 的描述。 version：API 的版本号。 termsOfService：服务条款的 URL。 contact：指定 @Contact 注解的对象，用于描述联系人信息。 license：指定 @License 注解的对象，用于描述许可证信息。
@Contact	定义 API 文档中的联系人信息	类、接口	name：联系人的名称。 url：联系人的网址。 email：联系人的电子邮件地址。
@License	定义 API 文档中的许可证信息	类、接口	name：许可证的名称。 url：许可证的网址。
@externalDocs	定义 API 文档中的额外信息	类、接口	description：信息的描述。 url：信息的网址。

同样是在WebConfigurer中配置，添加如下代码：

	@Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String appVersion) {
        return new OpenAPI()
                .info(new Info()                                          // ## API的基本信息，包括标题、版本号、描述、联系人等
                        .title("博客论坛系统 API")                             // Api接口文档标题（必填）
                        .description("博客论坛系统 前台用户和后台管理 API")      // Api接口文档描述
                        .version(appVersion)                                  // Api接口版本
                        .license(new License()                            // ## 联系人信息
                                .name("Apache2.0")                            // 授权名称
                                .url("http://springdoc.org"))                 // 授权信息
                        )
                        .contact(new Contact()                            // ## 作者信息
                                .name("奇妙方程式")                            // 作者名称
                                .email("229600398@qq.com")                    // 作者邮箱
                                .url("https://blog.csdn.net/weixin_45940369") // 介绍作者的URL地址
                        )
                .externalDocs(new ExternalDocumentation()                 // ## API的额外信息
                        .description("文档")                                  // 描述
                        .url("https://blog.csdn.net/weixin_45940369/article/details/141058944")); // 链接
    }

这里配置了一个自定义的配置参数springdoc.version（也可以直接写成1.0），所以需要把这个加到application.properties中

springdoc.version=1.0

重新启动，查看页面

5. 注解

swagger2 和 swagger3 的注解的区别

用途	swagger2	swagger3	注解位置	案例
给 API 分组	@Api	@Tag(name)	Controller类上	@Tag(name = “活动管理”)
描述 API 的操作	@ApiOperation	@Operation(summary)	Controller方法上	@Operation(summary = “新增活动接口”, description = “新增活动接口的说明”)
描述操作的输入参数	@ApiImplicitParams	@Parameters	Controller方法上
描述操作的输入参数	@ApiImplicitParam	@Parameter(description)	Controller方法上
描述操作的输入参数	@ApiParam	@Parameter(description)	Controller方法参数类上
描述操作的输入参数	@ApiIgnore	@Parameter(hidden=true) 或 @Operation(hidden=true) 或 @Hidden	类或方法或参数上
描述数据模型的属性	@ApiModel	@Schema	实体类上	@Schema(title=“活动对象”, description=“活动对象的全部字段属性”)
描述数据模型的属性	@ApiModelProperty	@Schema	实体类属性上	@Schema(description = “活动id”, requiredMode = Schema.RequiredMode.REQUIRED, example = “1”)

• title、name：名称
• description：描述
• requiredMode：指定该属性的必需性
  Schema.RequiredMode.REQUIRED 表示这个属性是必需
• example：提供该属性的示例值
  展示该属性的一个具体示例

参考文章
https://www.cnblogs.com/antLaddie/p/17418078.html
https://www.cnblogs.com/strongmore/p/18106597
https://www.jianshu.com/p/0c09b675c2d3
https://blog.csdn.net/weixin_59383491/article/details/135105646