介绍

MESH-PLATFORM 是一个全新的软件开发框架。

1:项目使用框架

• Knife4j: knife4j 自4.0版本开始，Knife4j提供对OpenAPI3规范的适配，底层规范解析框架依赖springdoc-openapi项目

2:配置

• 1：Gateway网关配置

knife4j:
  gateway:
    # ① 第一个配置，开启gateway聚合组件
    enabled: true
    # ② 第二行配置，设置聚合模式采用discover服务发现的模式
    strategy: discover
    discover:
      # ③ 第三行配置，开启discover模式
      enabled: true
      # ④ 第四行配置，聚合子服务全部为Swagger2规范的文档
      version: openapi3

• 2：模块配置

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
    show-extensions: true
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '//**' #需要配置单/，文档//是为了消除转义
      packages-to-scan: com.platform
knife4j:
  enable: false
  setting:
    language: zh_cn

3:自定义枚举解析

• 设计原由 @Schema注解可以将常见类型在Swagger文档描述中解析，但是一些装填标识类字段后端逐个补充填写耗时耗力，并且状态增删维护麻烦。所以需要自定义一个可以解析枚举描述，自动填充Swagger文档描述的注解来实现功能。

• 1：自定义SchemaEnum注解

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = EnumValidator.class)
public @interface SchemaEnum {

    /**
     * 枚举类说明
     */
    String description() default SymbolConst.BLANK;
    /**
     * 枚举类对象
     */
    Class<? extends BaseEnum<? extends Enum<?>,? extends Serializable>> value();
    /**
     * 默认值
     */
    String defaultValue() default SymbolConst.BLANK;
    /**
     * 是否隐藏
     */
    boolean hidden() default false;
    /**
     * 是否必须
     */
    boolean required() default false;
    /**
     * 数据类型
     */
    String dataType() default SymbolConst.BLANK;

    /**
     * 缺少报错：XXX contains Constraint annotation, but does not contain a message parameter
     */
    String message() default SymbolConst.BLANK;

    /**
     * 缺少报错：XXX contains Constraint annotation, but does not contain a groups parameter
     */
    Class<?>[] groups() default {};

    /**
     * 缺少报错：XXX contains Constraint annotation, but does not contain a payload parameter
     */
    Class<? extends Payload>[] payload() default {};

}

• 2：文档解析填充

@Component
public class SchemaPropertyExtend implements PropertyCustomizer {

    @Override
    public Schema customize(Schema schema, AnnotatedType type) {
        if (ObjectUtil.isEmpty(type.getCtxAnnotations())) {
            return schema;
        }
        //初始化描述
        StringBuilder description = new StringBuilder();
        //设置注解信息
        for (Annotation ctxAnnotation : type.getCtxAnnotations()) {
            if (ctxAnnotation.annotationType().equals(SchemaEnum.class)) {
                //设置必填项
                if(((SchemaEnum) ctxAnnotation).required()){
                    schema.setRequired(CollUtil.newArrayList(Boolean.TRUE.toString()));
                }
                //设置描述信息
                description.append(((SchemaEnum) ctxAnnotation).description());
                Class<? extends BaseEnum> clazz = ((SchemaEnum) ctxAnnotation).value();
                description.append(FormatUtil.getEnumDescJSON(clazz));
            }
        }
        //返回描述
        if (StrUtil.isNotEmpty(description)) {
            schema.setDescription(description.toString());
        }
        return schema;
    }

}

• 3：使用枚举

    /**
     * 表单类型
     */
    @SchemaEnum(value = FormTypeEnum.class,description = "表单类型")
    private Integer formType;

• 4：效果