SpringCloud + React19 集成Scalar的API文档
你好呀，我的老朋友！我是老寇，跟我一起学习集成Scalr API文档
众所周知，Knife4j是一个集Swagger2和OpenAPI3为一体的增强解决方案，但是社区不太活跃，再加上SpringBoot4发版，迫切需要一个集成OpenAPI 3.0和OpenAPI 3.1规范的增强解决方案，所以才集成Scalar
React集成Scalar
React集成Scalar文档地址
安装依赖
pnpminstall@scalar/api-reference-react配置详情
| 配置项 | 类型 | 是否必填 | 说明 | 示例 |
|---|---|---|---|---|
sources | Array | 是 | OpenAPI 文档源列表，一个配置可以配置多个 API 文档。 | [{ title: "认证授权", url: "/api/v3/api-docs" }] |
sources.title | String | 是 | API 文档名称，在 Scalar 左侧导航中显示。 | "认证授权" |
sources.url | String | 是 | OpenAPI（Swagger）JSON 文档地址。 | "/api-proxy/auth/api/v3/api-docs" |
sources.default | Boolean | 否 | 是否默认选中该文档。 | true |
proxyUrl | String | 否 | Scalar 的代理地址，用于 Try It、鉴权等请求代理。 | "/api-proxy/auth/scalar" |
expandAllResponses | Boolean | 否 | 是否默认展开所有 Response。 | true |
hideClientButton | Boolean | 否 | 是否隐藏 Generate Client（生成客户端）按钮。 | true |
orderRequiredPropertiesFirst | Boolean | 否 | Model 属性中，是否将必填字段排在前面。 | true |
expandAllModelSections | Boolean | 否 | 是否默认展开所有 Model 定义。 | false |
具体代码
apiDoc.tsx
import{ApiReferenceReact}from'@scalar/api-reference-react'import'@scalar/api-reference-react/style.css'import{useIntl}from'@@/exports';exportdefault()=>{constintl=useIntl();constt=(id:string,values?:Record<string,any>)=>intl.formatMessage({id},values);return(<ApiReferenceReact configuration={[{sources:[{title:'认证授权',url:"/api-proxy/auth/api/v3/api-docs",default:true,}],proxyUrl:"/api-proxy/auth/scalar",expandAllResponses:true,hideClientButton:true,orderRequiredPropertiesFirst:true,expandAllModelSections:false,},{sources:[{title:'后台管理',url:"/api-proxy/admin/api/v3/api-docs",default:true,}],proxyUrl:"/api-proxy/admin/scalar",expandAllResponses:true,hideClientButton:true,orderRequiredPropertiesFirst:true,expandAllModelSections:false,}]}/>);};Spring Cloud Gateway集成Scalar
由于代理地址为/**/scalar因此，需要在网关层将/**/scalar覆盖为scalar_url
依赖
<dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId> </dependency>具体代码
ScalarGatewayFilterFactory
@Slf4j@ComponentpublicclassScalarGatewayFilterFactoryextendsAbstractGatewayFilterFactory<ScalarGatewayFilterFactory.@NonNullConfig>implementsOrdered{publicScalarGatewayFilterFactory(){super(Config.class);}@OverridepublicintgetOrder(){returnOrdered.LOWEST_PRECEDENCE-2000;}@NonNull@OverridepublicGatewayFilterapply(Configconfig){return(exchange,chain)->{ServerHttpRequestrequest=exchange.getRequest();// 获取uriStringrequestURL=ReactiveRequestUtils.getRequestURL(request);// scalar重写地址if(ReactiveRequestUtils.pathMatcher("/**/scalar",requestURL)){StringscalarUrl=ReactiveRequestUtils.getParamValue(request,"scalar_url");URIuri=URI.create(scalarUrl);returnchain.filter(exchange.mutate().request(request.mutate().uri(uri).path(uri.getPath()).build()).build());}returnchain.filter(exchange);};}publicstaticclassConfig{}}application.yml
spring:cloud:gateway:server:webflux:enabled:trueroutes:-id:laokou-auth-scalaruri:lb://laokou-authpredicates:-Path=/api-gateway/auth/scalarfilters:-name:Scalar-id:laokou-admin-scalaruri:lb://laokou-adminpredicates:-Path=/api-gateway/admin/scalarfilters:-name:ScalarSpringBoot集成Scalar（以laokou-auth为例）
安装依赖
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-scalar</artifactId></dependency>具体代码
OpenApiDocConfig
@ConfigurationpublicclassOpenApiDocConfig{@BeanOpenAPIopenApi(){returnnewOpenAPI().info(newInfo().title("API文档").description("API文档").version("1.0.0").contact(newContact().name("laokou").url("https://github.com/KouShenhai").email("2413176044@qq.com")).license(newLicense().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0.html"))).externalDocs(newExternalDocumentation().description("老寇IoT云平台").url("https://github.com/KouShenhai")).addSecurityItem(newSecurityRequirement().addList(HttpHeaders.AUTHORIZATION)).components(newComponents().addSecuritySchemes(HttpHeaders.AUTHORIZATION,newSecurityScheme().name(HttpHeaders.AUTHORIZATION).type(SecurityScheme.Type.OAUTH2).in(SecurityScheme.In.HEADER).scheme("Bearer").bearerFormat("JWT")));}}application.yml
scalar:enabled:truespringdoc:swagger-ui:enabled:falseapi-docs:enabled:truepath:/v3/api-docsversion:openapi_3_1我是老寇，我们下次再见啦！