写在最前

如果这个项目让你有所收获，记得 Star 关注哦，这对我是非常不错的鼓励与支持。

源码地址（后端）：https://gitee.com/csps/mingyue

源码地址（前端）：https://gitee.com/csps/mingyue-ui

文档地址：https://gitee.com/csps/mingyue/wikis

开胃小菜

• 【接口篇】SpringBoot 整合 Swagger3 实现在线 API 文档
• 【接口篇】SpringBoot 整合 Swagger2 实现在线 API 文档

SpringFox 与 SpringDoc 注解差异

mingyue-gateway

引入依赖

<!-- 接口文档 -->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webflux-ui</artifactId>
</dependency>

SpringDocConfiguration

该类作为 Swagger 接口文档的聚合配置类，统一从网关入口进入 Swagger 文档中心。

@Configuration(proxyBeanMethods = false)
public class SpringDocConfiguration {/*** 当 swagger.enabled = true 向 Bean 容器中注册改对象* @return*/@Bean@Lazy(false)@ConditionalOnProperty(name = "swagger.enabled", havingValue = "true", matchIfMissing = true)public List<GroupedOpenApi> apis(SwaggerUiConfigParameters swaggerUiConfigParameters,SwaggerDocProperties swaggerProperties) {List<GroupedOpenApi> groups = new ArrayList<>();// 读取配置服务，添加接口分组，以服务为纬度进行分组for (String value : swaggerProperties.getServices().values()) {swaggerUiConfigParameters.addGroup(value);}return groups;}@Data@Component@ConfigurationProperties("swagger")public class SwaggerDocProperties {private Map<String, String> services;}
}

Nacos 添加配置 application-common.yml

swagger:# 是否开启接口文档enabled: truetitle: MingYue Swagger APIgateway: http://${GATEWAY_HOST:mingyue-gateway}:${GATEWAY-PORT:9100}token-url: ${swagger.gateway}/auth/oauth2/tokenscope: serverservices:mingyue-system-biz: systemmingyue-auth: auth

mingyue-common-doc

mingyue-common-doc 为本章节新增模块，主要用来管理微服务接口文档模块的依赖与配置

引入依赖

<dependencies><!-- 接口文档 v3 --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webmvc-core</artifactId></dependency><!-- 引入 swagger 页面 --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId></dependency><dependency><groupId>io.swagger.core.v3</groupId><artifactId>swagger-annotations</artifactId></dependency><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-commons</artifactId><scope>provided</scope></dependency><dependency><groupId>org.springframework</groupId><artifactId>spring-webmvc</artifactId><scope>provided</scope></dependency>
</dependencies>

添加配置项

/*** SwaggerProperties** @author Strive* @date 2023/6/22 11:00*/
@Data
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {/*** 是否开启 swagger*/private Boolean enabled = true;/*** 标题**/private String title = "";/*** 网关*/private String gateway;/*** 服务转发配置*/private Map<String, String> services;}

SwaggerAutoConfiguration

该类作为 Swagger 自动配置类，提供给需要接入 Swagger 文档的微服务们～

import com.csp.mingyue.doc.support.SwaggerProperties;
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 io.swagger.v3.oas.models.servers.Server;
import lombok.RequiredArgsConstructor;
import org.springdoc.core.SpringDocConfiguration;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.cloud.client.ServiceInstance;
import org.springframework.context.annotation.Bean;
import org.springframework.http.HttpHeaders;import java.util.ArrayList;
import java.util.List;/*** Swagger 配置** @author Strive*/
@RequiredArgsConstructor
@AutoConfiguration(before = SpringDocConfiguration.class)
@ConditionalOnProperty(name = "swagger.enabled", havingValue = "true", matchIfMissing = true)
@EnableConfigurationProperties(SwaggerProperties.class)
@ConditionalOnMissingClass("org.springframework.cloud.gateway.config.GatewayAutoConfiguration")
public class SwaggerAutoConfiguration {private final SwaggerProperties swaggerProperties;private final ServiceInstance serviceInstance;@Beanpublic OpenAPI springOpenAPI() {OpenAPI openAPI = new OpenAPI().info(new Info().title(swaggerProperties.getTitle()));// oauth2.0 passwordopenAPI.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));openAPI.schemaRequirement(HttpHeaders.AUTHORIZATION, this.securityScheme());// servers 提供调用的接口地址前缀（敲黑板，重点！！！！）List<Server> serverList = new ArrayList<>();String path = swaggerProperties.getServices().get(serviceInstance.getServiceId());serverList.add(new Server().url(swaggerProperties.getGateway() + "/" + path));openAPI.servers(serverList);return openAPI;}/*** 全局添加 token* @return SecurityScheme*/private SecurityScheme securityScheme() {SecurityScheme securityScheme = new SecurityScheme();// 类型securityScheme.setType(SecurityScheme.Type.APIKEY);// 请求头的 namesecurityScheme.setName(HttpHeaders.AUTHORIZATION);// token 所在位置securityScheme.setIn(SecurityScheme.In.HEADER);return securityScheme;}}

Nacos 添加配置 mingyue-gateway.yml

这一小节非常重要，我在这儿卡了很久很久，网关一直聚合微服务文档不成功

# 固定路由转发配置 无修改
- id: openapiuri: lb://mingyue-gatewaypredicates:- Path=/v3/api-docs/**filters:- RewritePath=/v3/api-docs/(?<path>.*), /$\{path}/v3/api-docs

如：http://mingyue-gateway:9100/v3/api-docs/system => http://mingyue-gateway:9100/system/v3/api-docs

启动测试

Swagger 地址

swagger-ui: http://mingyue-gateway:9100/swagger-ui.html

api-docs: http://mingyue-gateway:9100/system/v3/api-docs/

关闭 Swagger

通过 Nacos 配置 application-common.yml

swagger:# 是否开启接口文档enabled: false

小结

至此，SpringCloud Gateway 整合 SpringDoc 聚合其他微服务接口文档已经完成啦～

下一节再将还有一些需要完善的补充完整，休息休息～

本文链接：https://my.lmcjl.com/post/9370.html