MONI后台管理系统-swagger3(springdoc-openapi)集成

embedded/2024/12/23 4:28:44/

springdoc-openapi Java 库有助于使用 Spring Boot 项目自动生成 API 文档。springdoc-openapi 通过在运行时检查应用程序来根据 Spring 配置、类结构和各种注释推断 API 语义。
该库会自动生成 JSON/YAML 和 HTML 格式的页面文档。生成的文档可以使用swagger-api注释进行补充。
github地址 官网

1. 项目依赖版本

  • Spring-Boot: 3.1.0

2. 引入依赖

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

3. 配置

package com.omni.admin.swagger;import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import jakarta.annotation.Resource;
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;/*** SpringDoc配置**/
@Configuration
@ConditionalOnExpression("${springdoc.api-docs.enabled:true}")
public class SwaggerDocConfig {@Resourceprivate SwaggerDocProperties springDocProperties;@Beanpublic OpenAPI openAPI() {return new OpenAPI().info(new Info().title(springDocProperties.getTitle()).version(springDocProperties.getApplicationVersion())).addSecurityItem(new SecurityRequirement().addList(springDocProperties.getTokenName())).components(new Components().addSecuritySchemes(springDocProperties.getTokenName(),getSecurityScheme()));}private SecurityScheme getSecurityScheme(){return new SecurityScheme().name(springDocProperties.getTokenName()).in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.APIKEY).scheme("basic");}
}
package com.omni.admin.swagger;import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;import java.util.List;/*** swagger配置类**/
@Data
@Configuration
@ConfigurationProperties(prefix = "springdoc")
@ConditionalOnExpression("${springdoc.api-docs.enabled:true}")
public class SwaggerDocProperties {/*** 项目应用名*/@Value("${spring.application.name:接口文档}")private String applicationName;/*** 项目名称*/private String title = "Omni-Admin后台管理系统接口文档";/*** 项目版本信息*/private String applicationVersion = "1.0.0";/*** 项目描述信息*/private String applicationDescription;/*** 认证token的名称*/private String tokenName = "X-Access-Token";/*** 文档组配置*/private List<Group> groups;@Datapublic static class Group{private String modelName;/*** 组名称*/private String name;/*** 组所属的包*/private String packageName;}
}

4. properties配置

这里需要做一些说明:其中配置了排序相关和分模块。还有默认访问是全部文档是展开的,可以配置默认合并。

# springdoc接口文档配置 配置参考 springdoc.md
springdoc.api-docs.enabled=true
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=method
springdoc.group-configs[0].group=A-平台管理
springdoc.group-configs[0].packages-to-scan[0]=auth.platform.service.platform
springdoc.group-configs[1].group=B-标签管理
springdoc.group-configs[1].packages-to-scan[0]=auth.platform.service.tag
springdoc.group-configs[2].group=C-配置中心
springdoc.group-configs[2].packages-to-scan[0]=auth.platform.service.configcenter
springdoc.group-configs[3].group=D-日志管理
springdoc.group-configs[3].packages-to-scan[0]=auth.platform.service.log
springdoc.group-configs[4].group=F-监控管理
springdoc.group-configs[4].packages-to-scan[0]=auth.platform.service.monitor
springdoc.group-configs[5].group=G-文件管理
springdoc.group-configs[5].packages-to-scan[0]=auth.platform.service.file
springdoc.group-configs[6].group=H-WS消息管理
springdoc.group-configs[6].packages-to-scan[0]=auth.platform.service.websocket
# 该配置控制是否需要在界面显示过滤框
springdoc.swagger-ui.filter=true
# 该配置主要控制swagger显示是直接展开还是关闭 none 不默认展开  list 列出所有api  full直接展开所有api
springdoc.swagger-ui.doc-expansion=none

5. 访问

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

在这里插入图片描述

6. Controller示例

package com.omni.admin.controller;import com.omni.admin.common.result.ApiResult;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** 接口信息表*/
@Tag(name = "接口管理")
@RestController
@RequestMapping("/api-info")
public class ApiInfoController {@Operation(summary = "测试接口文档")@GetMapping("/demo")public ApiResult<Void> demo(){return ApiResult.success();}}

7. Springdoc-openapi 属性

springdoc-openapi依赖于使用标准文件位置的标准 Spring 配置属性(YML 或属性)。

7.1. Springdoc-OpenAPI 核心属性

参数名称默认值描述
springdoc.api-docs.path/v3/api-docsString,用于 Json 格式的 OpenAPI 文档的自定义路径。
springdoc.api-docs.enabledtrueBoolean.禁用 springdoc-openapi 端点(默认为 /v3/api-docs)。
springdoc.packages-to-scan*List of Strings.要扫描的包列表(逗号分隔)
springdoc.paths-to-match/*List of Strings.要匹配的路径列表(逗号分隔)
springdoc.produces-to-match-to/*List of Strings.生成要匹配的媒体类型列表(逗号分隔)
springdoc.headers-to-match/*List of Strings.要匹配的标头列表(逗号分隔)
springdoc.consumptions-to-matchs./*List of Strings.要匹配的消耗媒体类型列表(逗号分隔)
springdoc.paths-to-excludeList of Strings.要排除的路径列表(逗号分隔)
springdoc.packages-to-excludeList of Strings.要排除的包列表(逗号分隔)
springdoc.default-consumptions-media-typeapplication/jsonString.默认使用媒体类型。
springdoc.default-produces-media-type**/**String.默认生成媒体类型。
springdoc.cache.disabledfalseBoolean.禁用计算的 OpenAPI 的 springdoc-openapi 缓存。
弹簧文档显示执行器falseBoolean.显示执行器端点。
springdoc.auto-tag-classestrueBoolean.禁用 springdoc-openapi 自动标记。
springdoc.model-and-view-allowfalseBoolean.允许带有 ModelAndView 的 RestControllers 返回出现在 OpenAPI 描述中。
springdoc.override-with-generic-responsetrueBoolean.如果为 true,则自动将@ControllerAdvice响应添加到所有生成的响应中。
springdoc.api-docs.groups.enabledtrueBoolean.禁用 springdoc-openapi 组。
springdoc.group-configs[0].groupString.组名称
springdoc.group-configs[0].displayNameString.组的显示名称。
springdoc.group-configs[0].packages-to-scan*List of Strings.要扫描组的包列表(逗号分隔)
springdoc.group-configs[0].paths-to-match/*List of Strings.要为组匹配的路径列表(逗号分隔)
springdoc.group-configs[0].paths-to-exclude``List of Strings.要为组排除的路径列表(逗号分隔)
springdoc.group-configs[0].packages-to-excludeList of Strings.要为组排除的包列表(逗号分隔)
springdoc.group-configs[0].produces-to-match/*List of Strings.生成要匹配的媒体类型列表(逗号分隔)
springdoc.group-configs[0].consumes-to-match/*List of Strings.要匹配的消耗媒体类型列表(逗号分隔)
springdoc.group-configs[0].headers-to-match/*List of Strings.要匹配的标头列表(逗号分隔)
springdoc.webjars.prefix/webjarsString,要更改 webjars 前缀,该前缀可见 swagger-ui 的 URL 为 spring-webflux。
springdoc.api-docs.resolve-schema-propertiesfalseBoolean.在@Schema(名称、标题和说明)上启用属性解析程序。
springdoc.remove-broken-reference-definitiontrueBoolean.禁用删除损坏的引用定义。
springdoc.writer-with-default-pretty-printerfalseBoolean.启用OpenApi规范的漂亮打印。
springdoc.model-converters.deprecating-converter.enabledtrueBoolean.禁用弃用模型转换器。
springdoc.model-converters.polymorphic-converter.enabledtrueBoolean.禁用多态模型转换器。
springdoc.model-converters.pageable-converter.enabledtrueBoolean.禁用可分页模型转换器。
springdoc.model-converters.sort-converter.enabledtrueBoolean.禁用排序转换器。
springdoc.use-fqnfalseBoolean.启用完全限定名称。
springdoc.show-login-endpointfalseBoolean.使 Spring 安全登录端点可见。
springdoc.pre-load-enabledfalseBoolean.预加载设置,用于在应用程序启动时加载 OpenAPI。
springdoc.writer-with-order-by-keysfalseBoolean.启用确定性/字母顺序排序。
springdoc.use-management-portfalseBoolean.在执行器管理端口上公开招摇 UI。
springdoc.disable-i18nfalseBoolean.使用 i18n 禁用自动翻译。
springdoc.show-spring-cloud-functionstrueBoolean.显示弹簧云函数 Web 终结点。
springdoc.api-docs.versionopenapi_3_0String.选择或(使用值 )。OpenAPI 3.0``OpenAPI 3.1``OPENAPI_3_1
springdoc.default-flat-paramObjectfalseBoolean.默认平展参数。
springdoc.default-support-form-datafalseBoolean.在指定 api 以接受表单数据时默认设置表单数据的参数。

7.2. swagger-ui 属性

  • 上提供了对 swagger-ui 属性的支持。请参阅官方文档。springdoc-openapi
  • 您可以在文档中使用与 Spring 引导属性相同的 swagger-ui 属性。
    在这里插入图片描述
参数名称默认值描述
springdoc.swagger-ui.path/swagger-ui.htmlString,用于 swagger-ui HTML 文档的自定义路径。
springdoc.swagger-ui.enabledtrueBoolean.禁用 swagger-ui 端点(默认情况下为 /swagger-ui.html)。
springdoc.swagger-ui.configUrl/v3/api-docs/swagger-configString.要从中获取外部配置文档的 URL。
springdoc.swagger-ui.layoutBaseLayoutString.通过插件系统提供的组件的名称,用作 Swagger UI 的顶级布局。
springdoc.swagger-ui.validatorUrlvalidator.swagger.io/validator默认情况下,Swagger UI 会尝试根据 swagger.io 的在线验证器验证规范。您可以使用此参数设置不同的验证程序 URL,例如,对于本地部署的验证程序验证程序徽章。将其设置为 ,或者将禁用验证。none``127.0.0.1``localhost
springdoc.swagger-ui.tryItOutEnabledfalseBoolean.控制默认情况下是否应启用“试用”部分。
springdoc.swagger-ui.filterfalseBoolean OR String.如果设置,则启用筛选。顶部栏将显示一个编辑框,可用于筛选显示的标记操作。可以是用于启用或禁用的布尔值,也可以是字符串,在这种情况下,将使用该字符串作为筛选器表达式启用筛选。筛选区分大小写,与标记内任意位置的筛选器表达式匹配。
springdoc.swagger-ui.operationsSorterFunction=(a ⇒ a).对每个 API 的操作列表应用排序。它可以是“alpha”(按路径字母数字排序),“method”(按HTTP方法排序)或函数(参见Array.prototype.sort()以了解排序函数的工作原理)。默认值为服务器返回的顺序不变。
springdoc.swagger-ui.tagsSorterFunction=(a ⇒ a).对每个 API 的标记列表应用排序。它可以是“alpha”(按路径字母数字排序)或函数,请参阅 Array.prototype.sort() 以学习如何编写排序函数)。每次传递时,将两个标记名称字符串传递给分拣机。默认值是由 Swagger UI 确定的顺序。
springdoc.swagger-ui.oauth2RedirectUrl/swagger-ui/oauth2-redirect.htmlString.OAuth 重定向网址。
springdoc.swagger-ui.displayOperationIdfalseBoolean.控制操作 ID 在操作列表中的显示。缺省值为 。false
springdoc.swagger-ui.displayRequestDurationfalseBoolean.控制“试用”请求的请求持续时间(以毫秒为单位)的显示。
springdoc.swagger-ui.deepLinkfalseBoolean.如果设置为 ,则启用标签和操作的深层链接。有关更多信息,请参阅 [深层链接文档](/docs/usage/deep-linking.md)。true
springdoc.swagger-ui.defaultModelsExpandDepth1Number.模型的默认扩展深度(设置为 -1 将完全隐藏模型)。
springdoc.swagger-ui.defaultModelExpandDepth1Number.模型示例部分上模型的默认扩展深度。
springdoc.swagger-ui.defaultModelRenderingString=["example"*, "model"].控制首次呈现 API 时模型的显示方式。(用户始终可以通过单击“模型”和“示例值”链接来切换给定模型的渲染。
springdoc.swagger-ui.docExpansionString=["list"*, "full", "none"].控制操作和标记的默认展开设置。它可以是“列表”(仅展开标签)、“完整”(展开标签和操作)或“无”(不展开任何内容)。
springdoc.swagger-ui.maxDisplayTagsNumber.如果设置,将显示的标记操作数限制为最多此数量。默认值为显示所有操作。
springdoc.swagger-ui.showExtensionsfalseBoolean.控制供应商扩展 () 字段和操作、参数和架构的值的显示。x-
springdoc.swagger-ui.urlString.要配置,自定义 OpenAPI 文件的路径。如果使用,将被忽略。urls
springdoc.swagger-ui.showCommonExtensionsfalseBoolean.控制参数的扩展 (、、、、) 字段和值的显示。pattern``maxLength``minLength``maximum``minimum
springdoc.swagger-ui.supportedSubmitMethodsArray=["get", "put", "post", "delete", "options", "head", "patch", "trace"].启用了“试用”功能的 HTTP 方法列表。空数组禁用所有操作的“试用”。这不会从显示中过滤操作。
springdoc.swagger-ui.queryConfigEnabledfalseBoolean.自 以来禁用。此参数启用(旧版)通过 URL 搜索参数覆盖配置参数。在启用此功能之前,请参阅安全公告。v1.6.0
springdoc.swagger-ui.oauth. additionalQueryStringParamsString.添加到授权 URL 和令牌 URL 的其他查询参数。
springdoc.swagger-ui.disable-swagger-default-urlfalseBoolean.禁用 swagger-ui 默认宠物商店网址。(从 v1.4.1 开始可用)。
springdoc.swagger-ui.urls[0].urlURL.Topbar 插件使用的 swagger 组的 url。URL 在此数组中的所有项中必须是唯一的,因为它们用作标识符。
springdoc.swagger-ui.urls[0].nameString.Topbar 插件使用的 swagger 组的名称。名称在此数组中的所有项中必须是唯一的,因为它们用作标识符。
springdoc.swagger-ui.urlsPrimaryNameString.加载 Swagger UI 时将显示的招摇组的名称。
springdoc.swagger-ui.oauth.clientIdString.默认客户端 ID。必须是字符串。
springdoc.swagger-ui.oauth.clientSecretString.默认客户端机密。切勿在生产环境中使用此参数。它公开了重要的安全信息。此功能仅适用于开发/测试环境。
springdoc.swagger-ui.oauth.realmString.领域查询参数(适用于 OAuth 1)已添加到授权 URL 和令牌 URL。
springdoc.swagger-ui.oauth.appNameString.OAuth 应用程序名称,显示在授权弹出窗口中。
springdoc.swagger-ui.oauth.scopeSeparatorString.用于传递范围的 OAuth 范围分隔符,在调用之前进行编码,默认值为空格(编码值 %20)。
springdoc.swagger-ui.csrf.enabledfalseBoolean.启用 CSRF 支持
springdoc.swagger-ui.csrf.use-local-storagefalseBoolean.从本地存储获取 CSRF 令牌。
springdoc.swagger-ui.csrf.use-session-storagefalseBoolean.从会话存储中获取 CSRF 令牌。
springdoc.swagger-ui.csrf.cookie-nameXSRF-TOKENString.可选的 CSRF,用于设置 CSRF cookie 名称。
springdoc.swagger-ui.csrf.header-nameX-XSRF-TOKENString.可选的 CSRF,用于设置 CSRF 标头名称。
springdoc.swagger-ui.syntaxHighlight.activatedtrueBoolean.是否应激活语法突出显示。
springdoc.swagger-ui.syntaxHighlight.themeagateString…突出显示.js要使用的语法着色主题。(只有这 6 种样式可用。String=["agate"*, "arta", "monokai", "nord", "obsidian", "tomorrow-night"]
springdoc.swagger-ui.oauth. useBasicAuthentication WithAccessCodeGrantfalseBoolean.仅针对访问代码流激活。在对 tokenURL 的authorization_code请求期间,使用 HTTP 基本身份验证方案(具有基本 base64encode(client_id + client_secret)的授权标头)传递客户端密码。
springdoc.swagger-ui.oauth. usePkceWithAuthorization CodeGrantfalseBoolean.仅适用于授权代码流。代码交换的证明密钥为 OAuth 公共客户端带来了增强的安全性。
springdoc.swagger-ui.persistAuthorizationfalseBoolean.如果设置为 true,它将保留授权数据,并且在浏览器关闭/刷新时不会丢失
springdoc.swagger-ui.use-root-pathfalseBoolean.如果设置为 true,则可以直接从应用程序根路径访问 swagger-u。

8. Springdoc-openapi 实例

8.1. springdoc 应用实例

在这里插入图片描述

8.2 演示应用程序的源代码

https://github.com/springdoc/springdoc-openapi-demos.git

9. 从SpringFox迁移

  • 删除 springfox 和 swagger 2 依赖项。改为添加依赖项。springdoc-openapi-ui
 <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.14</version> </dependency>
  • 将 swagger 2 注释替换为 swagger 3 注释(它已包含在依赖项中)。 招摇 3 注释的包是 .springdoc-openapi-ui``io.swagger.v3.oas.annotations
    • @Api@Tag
    • @ApiIgnore→或或@Parameter(hidden = true)``@Operation(hidden = true)``@Hidden
    • @ApiImplicitParam@Parameter
    • @ApiImplicitParams@Parameters
    • @ApiModel@Schema
    • @ApiModelProperty(hidden = true)@Schema(accessMode = READ_ONLY)
    • @ApiModelProperty@Schema
    • @ApiOperation(value = "foo", notes = "bar")@Operation(summary = "foo", description = "bar")
    • @ApiParam@Parameter
    • @ApiResponse(code = 404, message = "foo")@ApiResponse(responseCode = "404", description = "foo")
  • 如果使用对象捕获多个请求查询参数,请使用@ParameterObject
  • 此步骤是可选的:仅当您有多个 bean 时,才将它们替换为 bean。Docket``GroupedOpenApi

以前:

 @Bean public Docket publicApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public")) .paths(PathSelectors.regex("/public.*")) .build() .groupName("springshop-public") .apiInfo(apiInfo()); } @Bean public Docket adminApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin")) .paths(PathSelectors.regex("/admin.*")) .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class)) .build() .groupName("springshop-admin") .apiInfo(apiInfo()); }

现在:

 @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("springshop-public") .pathsToMatch("/public/**") .build(); } @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("springshop-admin") .pathsToMatch("/admin/**") .addMethodFilter(method -> method.isAnnotationPresent(Admin.class)) .build(); }

如果你只有一个 - 删除它,而是将属性添加到你的 :Docket``application.properties

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**
 @Bean public OpenAPI springShopOpenAPI() { return new OpenAPI() .info(new Info().title("SpringShop API") .description("Spring shop sample application") .version("v0.0.1") .license(new License().name("Apache 2.0").url("http://springdoc.org"))) .externalDocs(new ExternalDocumentation() .description("SpringShop Wiki Documentation") .url("https://springshop.wiki.github.org/docs")); }

http://www.ppmy.cn/embedded/147975.html

相关文章

聚观早报 | 百度回应进军短剧;iPad Air将升级OLED

聚观早报每日整理最值得关注的行业重点事件&#xff0c;帮助大家及时了解最新行业动态&#xff0c;每日读报&#xff0c;就读聚观365资讯简报。 整理丨Cutie 12月18日消息 百度回应进军短剧 iPad Air将升级OLED 三星Galax S25 Ultra配色细节 一加Ace 5系列存储规格 小米…

呼入机器人:24小时客户服务的未来趋势

呼入机器人&#xff1a;24小时客户服务的未来趋势 作者&#xff1a;开源大模型智能呼叫中心系统FreeAICC&#xff0c;Github&#xff1a;https://github.com/FreeIPCC/FreeAICC 在当今快节奏的商业环境中&#xff0c;客户服务已成为企业竞争的核心要素之一。随着人工智能技术…

Spring篇--xml方式整合第三方框架

Spring xml方式整合第三方框架 xml整合第三方框架有两种整合方案&#xff1a; ​ 不需要自定义名空间&#xff0c;不需要使用Spring的配置文件配置第三方框架本身内容&#xff0c;例如&#xff1a;MyBatis&#xff1b; ​ 需要引入第三方框架命名空间&#xff0c;需要使用…

web组态软件开发详细流程介绍

什么是组态软件&#xff1f; 组态软件是一种用于创建、配置和管理各种工业控制系统的应用程序。它通过用户友好的图形界面和先进的功能&#xff0c;使工程师能够实时监控和控制复杂的工业过程。 一、组态软件的基本概念 1.1 组态软件的作用 组态软件在工业控制系统中起到关键…

Python 实现炸弹人游戏

一、引言 炸弹人游戏是一款经典的游戏&#xff0c;在本文中&#xff0c;我们将深入探讨如何使用 Python 的 Pygame 库来实现一个炸弹人游戏&#xff0c;并对其进行多方面的优化&#xff0c;包括添加敌人 AI、得分系统、生命值以及游戏结束逻辑&#xff0c;从而为玩家带来更完整…

Oracle Database 21c Express Edition数据库 和 Sqlplus客户端安装配置

目录 一. 前置条件二. Win10安装配置Oracle数据库2.1 数据库获取2.2 数据库安装2.3 数据库配置确认2.4 数据库访问 三. Win10配置Oracle数据库可对外访问3.1 打开文件和打印机共享3.2 开放1521端口 四. 端口与地址确认4.1 查看监听器的状态4.2 Win10查看1521端口是否被监听4.3 …

.Net Core框架创建一个Windows服务类型的应用程序

在NuGet中的包管理中添加两个包 System.ServiceProcess.ServiceController Microsoft.Extensions.Hosting.WindowsServices 在Program.cs中添加.UseWindowsService()&#xff0c;另外还需要设置管理员身份运行 Program.cs代码如下 public class Program {public static void…

BUUCTF-[SUCTF 2019]CheckIn -[WP]

进入环境、文件上传 先上传一句话 不能上传php后缀文件 改成图片后缀 <?被过滤 修改一下代码&#xff0c;上传 <script languagephp>eval($_POST[a]);</script> 返回exif_imagetype类型不对 exif_imagetype这个是php中的一个内置函数 用于判断一个给定文件…