Swagger扩展 - 同一个接口生成多份Swagger API文档
创始人
2024-05-28 20:03:52
0

为同一个@ApiOperation生成多份不同Swagger API文档。

0. 目录

      • 1. 背景
      • 2. 效果展示
      • 3. 实现
        • 3.1 关键逻辑 - 让接口自解释
        • 3.2 关键逻辑 - 如何生成相应的ApiDescription
        • 3.3 关键逻辑 - 如何为生成的ApiDescription 赋值
        • 3.4 关键逻辑 - 如何动态生成Docket
      • 4. 继续优化
      • 5. 参考

1. 背景

正规的软件开发流程里,要求都是先做设计,再进行开发;先写文档,再写实现。只是面对现实的时候,往往都是代码先行,文档则是之后有需要再说。

这个背景下,Swagger这类根据代码生成文档的工具也就有了连绵不绝的生命力。

而同样是在实际场景里,我们往往会因为某些原因,例如"遵循业内的既有标准",亦或是"降低接口使用者的使用门槛,减少心智负担"等等,让同一个接口实现多种功能。举个具体的例子就是,对于一些发布服务,发起流程类的接口,往往都是提供同一个URL入口地址,然后通过参数的不同来进行发起不同服务或流程的操作。

但世界上没有完美的事情,Swagger默认是一个@ApiOperation生成一个对应的API文档说明,但上面所举例的"发布服务,发起流程"中又是需要通过不同的传参来进行区分,这样矛盾就产生了 —— Swagger的默认实现里无法在不进行额外说明的情况下,让使用者自行分辨出不同的服务/流程需要传递哪些参数,以及哪些参数的基本校验规则。(当然你可以强行将所有的参数放在一个参数实体类里面,然后为不同的服务/流程类型创建不同的类型作为前面参数实体类的字段,组成这样的层级结构确实也可以减缓上面这个矛盾,但相信这个实现之下,Swagger前端展示时,浏览器的滚动条一定相当深)。

以上矛盾之下,这导致对于这类接口的使用时,使用者需要消耗大量的成本在反复的沟通确认上。人员更迭或时间长久之后,同样程度的沟通又得从头开始再来一次。使用者和提供者对此都是心力憔悴。

过往我们尝试通过编写文档来缓解上面的问题,但代码和文档分离的结果就是缺乏及时性,也缺乏快速验证的途径。

本文中我们尝试大幅缓解这个问题。借助Swagger扩展,实现同一个接口下,不同的服务/流程能够生成不同的swagger文档,以期提升接口文档的及时性和可验证性,从而大幅降低沟通成本。

2. 效果展示

以下为同一个接口所生成的两个Swagger API文档(可以看到它们是同一个url地址, 不同的请求参数):

  1. 流程服务1
    流程服务1
  2. 流程服务2
    流程服务2

3. 实现

首先让我们列举下实现这个需求过程中可能遇到的一些难点,然后针对性地进行解决方案介绍。

  1. 如何让目标接口拥有自解释"自己这个接口需要被生成多个API文档"的能力。
  2. 在第一步基础上,如何生成相应的API文档所对应的Swagger内部数据结构,参与到Swagger生命周期中,最小化我们的工作量。
  3. 如何为第二步生成的Swagger内部数据结构赋值。注意这里的赋值分为了入参和出参的解析赋值,以及其它诸如http method等的赋值。这一部分我们放在下面专门的小节里进行介绍。
  4. 如何让最终生成并且填充完毕的Swagger内部数据结构在前端页面正常展示。在Swagger的 restful接口返回值(准确说是openapi返回值规范)中,接口的唯一性是由uri所实现的,但本文我们的需求里恰恰就是要求生成的多个接口文档拥有相同的uri,这个矛盾应该如何缓解?

针对以上几个问题,有以下让我们分别进行解决。

3.1 关键逻辑 - 让接口自解释

这里我们采用的是自定义注解的方式。然后通过在某个接口上标注相应个数的注解,来声明该接口需要生成相应个数的API文档,同时通过声明相应的注解属性来兼顾个性化需求和通用性处理之间的平衡。

相关代码如下:

// ============================================================ 自定义注解
// 使用Java8的"重复性注解"特性, 优化使用体验.
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface FlowTypes {FlowType[] value();
}// 代表一个被支持的流程类型
@Repeatable(FlowTypes.class)
@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FlowType {// 流程类型的名称String name();// 发起该流程时候, 需要传递的参数类型. 很明显, 我们建议使用自定义类型封装所有的请求参数Class paramType();
}// ============================================================
// 为了后面解析的方便, 这里我们还是使用了java8以前的使用方式.
// 以下就是代表该接口支持发送两类流程服务
@FlowTypes({ //@FlowType(name = "流程服务1", paramType = FlowServiceParams1.class), //@FlowType(name = "流程服务2", paramType = FlowServiceParams2.class) //
})
@ApiOperation(value="createFlowService")
@ResponseBody
@PostMapping("/createFlowService")
public Result createFlowService() {return new Result();
}

3.2 关键逻辑 - 如何生成相应的ApiDescription

这里我们采取的是实现Swagger提供的对外扩展接口ApiListingScannerPlugin

直接上代码。

@Component
public class SwaggerAddApiDescriptionPlugin implements ApiListingScannerPlugin {private final TypeResolver typeResolver;/*** 参考 ApiDescriptionLookup.java*/private Map needDealed = new HashMap<>();public Map getNeedDealed() {return Collections.unmodifiableMap(needDealed);}	@Autowiredpublic SwaggerAddApiDescriptionPlugin(TypeResolver typeResolver) {this.typeResolver = typeResolver;}@Overridepublic List apply(DocumentationContext documentationContext) {return generateApiDesc(documentationContext);}private List generateApiDesc(final DocumentationContext documentationContext) {List requestHandlers = documentationContext.getRequestHandlers();List newArrayList = new ArrayList<>();requestHandlers.stream().filter(s -> s.findAnnotation(FlowTypes.class).isPresent()).forEach(handler -> {List apiDescriptions = addApiDescriptions(documentationContext, handler);newArrayList.addAll(apiDescriptions);if (!apiDescriptions.isEmpty()) {needDealed.put(handler, GeneratedApis.builder().ads(apiDescriptions).build());}					});return newArrayList;}private List addApiDescriptions(DocumentationContext documentationContext,RequestHandler handler) {Optional annotation = handler.findAnnotation(FlowTypes.class);List apiDescriptionList = new ArrayList<>();if (annotation.isPresent()) {FlowTypes FlowTypes = annotation.get();String tagName = FlowTypes.name();// 确保归类在不同的group下, 以实现相同path的共存Arrays.stream(FlowTypes.value()).filter(FlowType -> FlowType.name().equalsIgnoreCase(documentationContext.getGroupName())).forEach(FlowType -> apiDescriptionList.addAll(addApiDescription(handler, documentationContext, FlowType, tagName)));}return apiDescriptionList;}private List addApiDescription(RequestHandler handler,DocumentationContext documentationContext,FlowType FlowType, String tagName) {RequestHandlerKey requestHandlerKey = handler.key();final String value = FlowType.value();OperationBuilder operationBuilder = new OperationBuilder(new CachingOperationNameGenerator()).summary(value).notes(value).tags(CollUtil.newHashSet(tagName + "-" + value));final ApiDescriptionBuilder builder = new ApiDescriptionBuilder(documentationContext.operationOrdering());builder.description(value).groupName(documentationContext.getGroupName()).hidden(false);List apiDescriptionList = new ArrayList<>();Iterator methodIterator = requestHandlerKey.getSupportedMethods().iterator();Iterator pathIterator = requestHandlerKey.getPathMappings().iterator();while (methodIterator.hasNext()) {List parameters = createParameter(FlowType,requestHandlerKey.getSupportedMediaTypes(), operationBuilder.build().getMethod());// 设置参数operationBuilder.parameters(parameters);operationBuilder.uniqueId(value + IdUtil.fastUUID());while (pathIterator.hasNext()) {// 设置请求路径builder.path(pathIterator.next());List operations = Arrays.asList(operationBuilder.build());apiDescriptionList.add(builder.operations(operations).build());}}return apiDescriptionList;}/*** 解析参数* @param FlowType* @param consumes* @param method* @return*/private List createParameter(FlowType FlowType,Set consumes, HttpMethod method) {final Class paramType = FlowType.dataTypeClass();final Map fieldMap = ReflectUtil.getFieldMap(paramType);return fieldMap.entrySet().stream().map(kv -> {Field field = kv.getValue();ApiModelProperty annotation = field.getAnnotation(ApiModelProperty.class);ParameterBuilder parameterBuilder = new ParameterBuilder();ResolvedType resolve = typeResolver.resolve(field.getType());return parameterBuilder.description(annotation.value())//参数数据类型.type(resolve)//参数名称.name(field.getName())//参数默认值.defaultValue(annotation.name())//参数类型 query、form、formdata.parameterType(findParameterType(resolve, consumes, method)).parameterAccess(annotation.access())//是否必填.required(annotation.required())//参数数据类型.modelRef(modelReference(resolve)).build();}).collect(Collectors.toList());}/*** 设置返回值model* @param type* @return*/private ModelReference modelReference(ResolvedType type) {if (Void.class.equals(type.getErasedType()) || Void.TYPE.equals(type.getErasedType())) {return new ModelRef("void");}if (MultipartFile.class.isAssignableFrom(type.getErasedType())|| isListOfFiles(type)) {return new ModelRef("__file");}return new ModelRef(type.getTypeName(),type.getBriefDescription(),null,allowableValues(type),type.getBriefDescription());}private static String findParameterType(ResolvedType resolvedType,Set consumes, HttpMethod method) {//Multi-part file trumps any other annotationsif (isFileType(resolvedType) || isListOfFiles(resolvedType)) {return "form";} else {return determineScalarParameterType(consumes, method);}}private static String determineScalarParameterType(Set consumes,HttpMethod method) {String parameterType = "query";if (consumes.contains(MediaType.APPLICATION_FORM_URLENCODED)&& method == HttpMethod.POST) {parameterType = "form";} else if (consumes.contains(MediaType.MULTIPART_FORM_DATA)&& method == HttpMethod.POST) {parameterType = "formData";}return parameterType;}private static boolean isListOfFiles(ResolvedType parameterType) {return isContainerType(parameterType) && isFileType(collectionElementType(parameterType));}private static boolean isFileType(ResolvedType parameterType) {return MultipartFile.class.isAssignableFrom(parameterType.getErasedType());}@Overridepublic boolean supports(DocumentationType documentationType) {return DocumentationType.SWAGGER_2.equals(documentationType);}@Builder(toBuilder = true)@Datapublic static class GeneratedApis {List ads;// 来源于哪个group//String groupNameOfSource;}	

3.3 关键逻辑 - 如何为生成的ApiDescription 赋值

关于这一步,细分之下,其实有三个维度:

  1. 诸如请求方式,请求数据类型等等。
  2. 请求入参。 这一步在上面的步骤二中已经完成了,不够完美,但先凑活用。
  3. 请求返回值。

继续上代码。解决上面三个维度中的第一和第三两个。

/*** 

搭配 {@code SwaggerAddApiDescriptionPlugin } 实现新增的 ApiDescription属性填充*

需要确保执行时机低于 {@code DocumentationPluginsBootstrapper}*

但{@code DocumentationPluginsBootstrapper} 这个玩意的执行时机为最低*

所以我们转而实现 ApplicationListener* @author fulizhe**/ @Component @Order(Ordered.LOWEST_PRECEDENCE) public class SwaggerAddAddtionApiDescriptionWithDeferPushValue implements ApplicationListener {private AtomicBoolean initialized = new AtomicBoolean(false);private final ApiDescriptionLookup lookup;private final SwaggerAddApiDescriptionPlugin swaggerAddApiDescriptionPlugin;@Autowiredprivate DocumentationCache cocumentationCache;public SwaggerAddAddtionApiDescriptionWithDeferPushValue(ApiDescriptionLookup lookup,SwaggerAddApiDescriptionPlugin swaggerAddApiDescriptionPlugin) {super();this.lookup = lookup;this.swaggerAddApiDescriptionPlugin = swaggerAddApiDescriptionPlugin;}void start() {if (initialized.compareAndSet(false, true)) {if (swaggerAddApiDescriptionPlugin.getNeedDealed().isEmpty()) {initialized.compareAndSet(true, false);return;}swaggerAddApiDescriptionPlugin.getNeedDealed().forEach((k, v) -> {if (v.ads.isEmpty()) {return;}ApiDescription sourceDescription = lookup.description(k);if (!Objects.isNull(sourceDescription)) { // 如果将 OneInterfaceMultiApiDescriptionController.createFlowService() 设置为hidden, 则这里判断失败List ads = v.ads;ApiDescription first = ads.get(0);// 这里所复制的就是请求方式,请求数据类型等等这些信息copyProperties(sourceDescription.getOperations().get(0), first.getOperations().get(0));// ============================== 设置返回值// 这里的思路是这样的:// 1. swagger中对于自定义类型的返回值显示采取的是 ref 引用的方式. (这一点可以随便找个swagger文档F12看一下), 同时将ref所引用的model定义放在整个接口最外层的definitions字段中// 2. 在上面的copyProperties(...)中我们已经复制response相关信息, 接下来我们就只需要将definitions相关信息拷贝到当前document之下就大功告成了Documentation matchedSourceDocumentationByGroup = matchedSourceDocumentationByGroup(sourceDescription);Documentation targetDocumentationByGroup = cocumentationCache.documentationByGroup(first.getGroupName().get());Map> tartgetApiListings = targetDocumentationByGroup.getApiListings();String srouceGroupName = sourceDescription.getGroupName().get();List list = matchedSourceDocumentationByGroup.getApiListings().get(srouceGroupName);// 确保返回值正常显示list.forEach(xv -> {tartgetApiListings.forEach((yk, yv) -> {yv.forEach(m -> ReflectUtil.setFieldValue(m, "models", xv.getModels()));});});}});}}private Documentation matchedSourceDocumentationByGroup(ApiDescription sourceDescription) {String srouceGroupName = sourceDescription.getGroupName().get();Optional findFirst = cocumentationCache.all().values().stream().filter(v -> v.getApiListings().keySet().contains(srouceGroupName)).findFirst();return findFirst.get();}private void copyProperties(Operation src, Operation dest) {final HttpMethod method = src.getMethod();ReflectUtil.setFieldValue(dest, "method", method);final ModelReference responseModelOfSource = src.getResponseModel();ReflectUtil.setFieldValue(dest, "responseModel", responseModelOfSource);final int position = src.getPosition();ReflectUtil.setFieldValue(dest, "position", position);final Set produces = src.getProduces();ReflectUtil.setFieldValue(dest, "produces", produces);final Set consumes = src.getConsumes();ReflectUtil.setFieldValue(dest, "consumes", consumes);final Set protocol = src.getProtocol();ReflectUtil.setFieldValue(dest, "protocol", protocol);ReflectUtil.setFieldValue(dest, "isHidden", src.isHidden());ReflectUtil.setFieldValue(dest, "securityReferences", src.getSecurityReferences());ReflectUtil.setFieldValue(dest, "responseMessages", src.getResponseMessages());ReflectUtil.setFieldValue(dest, "deprecated", src.getDeprecated());ReflectUtil.setFieldValue(dest, "vendorExtensions", src.getVendorExtensions());// 不拷貝以下屬性// summary, notes, uniqueId, tags, parameters// 無效, 这个拷贝需要目标属性有setXX方法// BeanUtil.copyProperties(src, dest, "parameters", "uniqueId", "summary", "notes", "tags");}@Overridepublic void onApplicationEvent(ContextRefreshedEvent event) {start();} }

3.4 关键逻辑 - 如何动态生成Docket

在Swagger内部数据类型实例填充完毕之后,就只剩下最后的一个问题:如何让最终生成并且填充完毕的Swagger内部数据结构在前端页面正常展示?

在Swagger的 restful接口返回值(准确说是openapi返回值规范)中,接口的唯一性是由uri所实现的,但本文我们的需求里恰恰就是要求生成的多个接口文档拥有相同的uri。

当下我们采取的让不同的流程服务出现在不同的group之下。
在这里插入图片描述
相关代码如下:

@Configuration
@EnableKnife4j
@EnableSwagger2WebMvc
public class SwaggerConfig {private DefaultListableBeanFactory context;private RequestMappingHandlerMapping handlerMapping;public SwaggerConfig(DefaultListableBeanFactory context,RequestMappingHandlerMapping handlerMapping) {this.context = context;this.handlerMapping = handlerMapping;dynamicCreate();}private void dynamicCreate() {// 分组Set groupNames = getGroupName();// 根据分好的组,循环创建配置类并添加到容器中groupNames.forEach(item -> {Docket docket = new Docket(DocumentationType.SWAGGER_2).groupName(item).select().apis(RequestHandlerSelectors.basePackage("cn.com.kanq.dynamic")) // 确保生成的Docket扫不到任何可以生成API文档的注解.paths(PathSelectors.any()).build();// 手动将配置类注入到spring bean容器中context.registerSingleton("dynamicDocket" + item, docket);});}private Set getGroupName() {HashSet set = new HashSet<>();Map mappingHandlerMethods = handlerMapping.getHandlerMethods();for (Map.Entry map : mappingHandlerMethods.entrySet()) {HandlerMethod method = map.getValue();GisServiceTypes gisServiceTypes = method.getMethod().getAnnotation(GisServiceTypes.class);if (null != gisServiceTypes) {GisServiceType[] value = gisServiceTypes.value();for (GisServiceType gisServiceType : value) {set.add(gisServiceType.name());}}}return set;}
}

4. 继续优化

  1. 关于请求参数的解析,最好复用swagger的解析。
  2. 让不同的服务出现在同一个页面之下。

5. 参考

  1. Gitee - easyopen。本文介绍的方法是基于swagger扩展实现,主要目的是站在巨人的肩膀上,最大化复用前辈们的成果。你说我从零开始写一个不就不需要这么多细节扣来扣去了,那么你可以参考下这个库。
  2. SWAGGER除了注解方式之外自定义添加接口,额外定义接口

相关内容

热门资讯

谷歌框架和安卓系统,构建智能移... 你有没有想过,为什么你的手机那么聪明,能帮你找到路线,还能帮你拍出美美的照片呢?这都要归功于一个超级...
安卓系统和oppo系统哪个流畅... 你有没有想过,手机系统哪个更流畅呢?安卓系统和OPPO系统,这两个名字听起来就让人心动。今天,咱们就...
安卓怎么用微软系统,利用微软系... 你是不是也和我一样,对安卓手机上的微软系统充满了好奇?想象那熟悉的Windows界面在你的安卓手机上...
安卓系统如何安装nfc,安卓系... 你有没有想过,用手机刷公交卡、支付账单,是不是比掏出钱包来得酷炫多了?这就得归功于NFC技术啦!今天...
ios系统可以转安卓,跨平台应... 你有没有想过,你的iPhone手机里的那些宝贝应用,能不能搬到安卓手机上继续使用呢?没错,今天就要来...
iOSapp移植到安卓系统,i... 你有没有想过,那些在iOS上让你爱不释手的app,是不是也能在安卓系统上大放异彩呢?今天,就让我带你...
现在安卓随便换系统,探索个性化... 你知道吗?现在安卓手机换系统简直就像换衣服一样简单!没错,就是那种随时随地、随心所欲的感觉。今天,就...
安卓系统安装按钮灰色,探究原因... 最近发现了一个让人头疼的小问题,那就是安卓手机的安装按钮突然变成了灰色,这可真是让人摸不着头脑。你知...
安卓7.1.1操作系统,系统特... 你知道吗?最近我在手机上发现了一个超级酷的新玩意儿——安卓7.1.1操作系统!这可不是什么小打小闹的...
安卓os系统怎么设置,并使用`... 你有没有发现,你的安卓手机有时候就像一个不听话的小孩子,有时候设置起来真是让人头疼呢?别急,今天就来...
安卓降低系统版本5.1,探索安... 你知道吗?最近安卓系统又来了一次大动作,竟然把系统版本给降到了5.1!这可真是让人有点摸不着头脑,不...
解放安卓系统被保护,解放安卓系... 你有没有想过,你的安卓手机其实可以更加自由地呼吸呢?是的,你没听错,我说的就是解放安卓系统被保护的束...
校务帮安卓系统下载,便捷校园生... 你有没有想过,你的手机里装了一个神奇的助手——校务帮安卓系统下载?没错,就是那个能让你轻松管理学校事...
安卓系统没有拼多多,拼多多崛起... 你知道吗?最近我在手机上发现了一个小小的秘密,那就是安卓系统里竟然没有拼多多这个应用!这可真是让我大...
甜城麻将安卓系统,解锁全新麻将... 你有没有听说过那个超级火的甜城麻将安卓系统?没错,就是那个让无数麻将爱好者为之疯狂的软件!今天,就让...
安卓系统卸载的软件,深度揭秘卸... 手机里的软件越来越多,是不是感觉内存不够用了?别急,今天就来教你怎么在安卓系统里卸载那些不再需要的软...
安卓系统推荐好游戏,畅享指尖乐... 手机里的游戏可是咱们休闲娱乐的好伙伴,尤其是安卓系统的用户,选择面那可是相当广呢!今天,就让我来给你...
王者安卓系统怎么卖,揭秘如何轻... 你有没有听说最近王者安卓系统的火爆程度?没错,就是那个让无数玩家沉迷其中的王者荣耀!今天,我就来给你...
安卓开发系统内置证书,基于安卓... 你有没有想过,你的安卓手机里那些神秘的内置证书,它们到底是个啥玩意儿?别急,今天就来给你揭秘这些隐藏...
荣耀安装安卓原生系统,深度体验... 你知道吗?最近荣耀手机界可是掀起了一股热潮,那就是——荣耀安装安卓原生系统!这可不是什么小打小闹,而...