swagger 接口参数顺序_swagger扩展为按代码定义顺序展示接口和字段_探索生活的少女的博客-CSDN博客
1. 存在的问题
我们在项目中使用swagger2.0时，发现如下问题：
我们想要按字段排序必须显示声明排序字段@ApiModelProperty(position=0)
swagger对注解@ApiOperation不支持position属性了，即不能按照指定接口顺序排序。(ps:官方也不提供解决，说设计如此，通过接口地址来排序。链接)
2.解决方法
查询官网
使用对应的扩展插件(ModelPropertyBuilderPlugin、OperationBuilderPlugin)
2.1使用ModelPropertyBuilderPlugin按代码顺序展示请求和响应字段
可以参考ModelPropertyBuilderPlugin的实现类ApiModelPropertyPropertyBuilder来实现自己的插件，
大概实现思路为：获取到字段上有ApiModelProperty注解的字段所在的类，然后获取所有字段数组，看这个字段在数组的哪个位置，就设置position属性。
实现代码如下：
/**
* 通过编写插件实现字段按类变量定义顺序排序,丰富模型属性
*/
@Component
public class CustomApiModelPropertyPositionBuilder implements ModelPropertyBuilderPlugin {undefined
private Log log = LogFactory.getLog(getClass());
@Override
public boolean supports(DocumentationType delimiter) {undefined
return SwaggerPluginSupport.pluginDoesApply(delimiter);
}
@Override
public void apply(ModelPropertyContext context) {undefined
Optional beanPropertyDefinitionOpt = context.getBeanPropertyDefinition();
Optional annotation = Optional.absent();
if (context.getAnnotatedElement().isPresent()) {undefined
annotation = annotation.or(findApiModePropertyAnnotation(context.getAnnotatedElement().get()));
}
if (context.getBeanPropertyDefinition().isPresent()) {undefined
annotation = annotation.or(findPropertyAnnotation(context.getBeanPropertyDefinition().get(), ApiModelProperty.class));
}
//必须是有ApiModelProperty注解的字段，并且beanPropertyDefinitionOpt带有注解
if (annotation.isPresent() && beanPropertyDefinitionOpt.isPresent()) {undefined
BeanPropertyDefinition beanPropertyDefinition = beanPropertyDefinitionOpt.get();
//获取到注解字段
AnnotatedField field = beanPropertyDefinition.getField();
//获取到字段所在的类
Class> clazz = field.getDeclaringClass();
//获取类中所有字段
Field[] declaredFields = clazz.getDeclaredFields();
Field declaredField;//获取当前字段的Field
try {undefined
declaredField = clazz.getDeclaredField(field.getName());
} catch (NoSuchFieldException | SecurityException e) {undefined
log.error("", e);
return;
}
//获取当前字段在数组中的位置。然后设置position属性
int indexOf = ArrayUtils.indexOf(declaredFields, declaredField);
if (indexOf != -1) {undefined
context.getBuilder().position(indexOf);
}
}
}
}
2.2使用OperationBuilderPlugin按代码顺序展示请求接口
可以参考OperationBuilderPlugin的实现类OperationHiddenReader来实现自己的插件，
大概实现思路为：获取到接口上有ApiOperation注解所在的类，然后获取到该接口方法在类中的多少行，用行号来进行接口排序。
实现代码如下：
/**
* 通过编写插件实现接口按定义顺序排序
*/
@Component
public class CustomOperationBuilderPlugin implements OperationBuilderPlugin {undefined
private static final Logger log = LoggerFactory.getLogger(CustomOperationBuilderPlugin.class);
@Override
public boolean supports(DocumentationType documentationType) {undefined
return SwaggerPluginSupport.pluginDoesApply(documentationType);
}
@Override
public void apply(OperationContext context) {undefined
//1.没有ApiOperation注解的直接返回
Optional apiOperation = context.findAnnotation(ApiOperation.class);
if (!apiOperation.isPresent()) {undefined
return;
}
//2.获取当前方法的位置，然后设置进position中
try {undefined
Class extends OperationContext> operationContextClass = context.getClass();
Field requestContextFiled = operationContextClass.getDeclaredField("requestContext");
requestContextFiled.setAccessible(true);
RequestMappingContext requestContext = (RequestMappingContext) requestContextFiled.get(context);
Class extends RequestMappingContext> requestContextClass = requestContext.getClass();
Field handler = requestContextClass.getDeclaredField("handler");
handler.setAccessible(true);
RequestHandler requestHandler = (RequestHandler) handler.get(requestContext);
//得到当前handler对应的Controller
Class> aClass = requestHandler.declaringClass();
//获取所有方法
// Method[] declaredMethods = aClass.getDeclaredMethods();
//获取当前api对应哪个方法
Method nowMethod = requestHandler.getHandlerMethod().getMethod();
//等到当前方法在所有方法中的位置(TO:位置变成了编译后的位置，需要找到编译前的位置)
// int indexOf = ArrayUtils.indexOf(declaredMethods, nowMethod);
//使用javasisit获取到对应方法在原始类的多少行
int indexOf = getMethodOriginalLine(aClass, nowMethod);
if (indexOf != -1) {undefined
//swagger-ui高版本不支持position排序了，解决方法是引入knife4j-spring-ui
//ps:找不到swagger-ui前端页面源代码加载位置，所以搞不定了~~~。有能力的小伙伴可以直接去修改swagger-ui的前端源代码
context.operationBuilder().position(indexOf);
//添加扩展参数：x-order(支持knife4j-spring-ui)
context.operationBuilder().extensions(Lists.newArrayList(new StringVendorExtension("x-order", indexOf + "")));
}
} catch (Exception e) {undefined
log.warn("加载swagger中方法api={}，设置顺序出错。", context.getName(), e);
}
}
/**
* 获取方法在类中的原始开始行数
*
* @param clazz 原始类
* @param nowMethod 需要查找的哪个方法
* @return
*/
private int getMethodOriginalLine(Class clazz, Method nowMethod) throws Exception {undefined
ClassPool pool = ClassPool.getDefault();
String className = clazz.getName();
CtClass cc = pool.get(className);
Class>[] parameterTypes = nowMethod.getParameterTypes();
String[] objects = Arrays.stream(parameterTypes).map(Class::getName).collect(Collectors.toList()).toArray(new String[]{});
return cc.getDeclaredMethod(nowMethod.getName(), pool.get(objects)).getMethodInfo().getLineNumber(0);
}
}
3.注意事项
原来swagger-ui.html地址也会保留
访问地址： http://ip:port/doc.html
使用到的包：
用于获取接口在源代码中的行数：
org.javassist
javassist
3.21.0-GA
用于前端页面展示：
com.github.xiaoymin
knife4j-spring-ui
2.0.8
4.参考资料
原网址: 访问
创建于: 2021-12-02 17:22:46
目录: default
标签: 无
未标明原创文章均为采集，版权归作者所有，转载无需和我联系，请注明原出处，南摩阿彌陀佛，知识，不只知道，要得到
最新评论