011-从零搭建微服务-接口文档（一）

原创

已于 2023-12-27 19:21:48 修改 · 1.7k 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#微服务 #java #架构

于 2023-06-23 14:30:51 首次发布

文章介绍了如何使用SpringDoc替换SpringFox作为API文档工具，并展示了如何在SpringCloudGateway中聚合各个微服务的接口文档。通过配置SpringDoc，实现了接口文档的在线查看和测试功能，并提供了详细的配置步骤和代码示例。

写在最前

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

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

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

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

开胃小菜

如果对接口文档不了解可以先看看下面的一些推荐阅读，简单了解一哈，不过已经不推荐使用了，之前使用 SpringFox 实现的。

首先 SpringFox 停止维护，很多 Bug 也不会修复了，其次 SpringDoc 基于 javadoc 无注解零入侵生成规范的 Openapi 结构体是行业规范，很多工具都支持接入，如：Apifox、Postman等。

SpringFox 与 SpringDoc 注解差异

Swagger	SpringDoc	JavaDoc
@jApi(name = “xxx”)	@Tag(name = “xxx”)	java类注释第一行
@Api(description= “xxx”)	@Tag(description= “xxx”)	java类注释
@ApiOperation	@Operation	java方法注释
@ApiIgnore	@Hidden	无
@ApiParam	@Parameter	java方法@param参数注释
@ApiImplicitParam	@Parameter	java方法@param参数注释
@ApiImplicitParams	@Parameters	多个@param参数注释
@ApiModel	@Schema	java实体类注释
@ApiModelProperty	@Schema	java属性注释
@ApiModelProperty(hidden = true)	@Schema(accessMode = READ_ONLY)	无
@ApiResponse	@ApiResponse	java方法@return返回值注释

mingyue-gateway

引入依赖

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

SpringDocConfiguration

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

@ConditionalOnProperty 注解用来指定如果配置文件中未进行对应属性配置时的默认处理：默认情况下matchIfMissing 为 false，也就是说如果未进行属性配置，则自动配置不生效。如果 matchIfMissing 为 true，则表示如果没有对应的属性配置，则自动配置默认生效。

@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"