历经14天自定义3个注解解决项目的3个Swagger难题

<!-- 引入swgger相关依赖       -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- springfox的UI。此依赖不是必须的 -->
<!--
   <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
-->

<!--基于BootStrap的UI框架-->
<!--2.x.x版本的swagger-bootstrap-ui引用包方式如下 1.9.x和2.x.x选择一个包引用就行-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索最新版本号-->
    <version>2.0.4</version>
</dependency>

/**
 * SwaggerConfig file
 * zhenghui
 */
@Configuration
@EnableSwagger2
@EnableKnife4j //UI
public class Swagger2Config {
    @Bean
    public Docket appApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false) //去掉默认的状态响应码
                .groupName("知识库")
                .apiInfo(apiInfo())
                .select()
                //扫描指定的包
//                .apis(RequestHandlerSelectors.basePackage("com.glodon.demo.mybatis")) //扫描的包
                //扫描只包含Swagger的注解，这种方式灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 配置Swagger信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("知识库接口文档")
                .description("该文档主要提供知识库后端的接口 \r\n\n")
                .contact(new springfox.documentation.service.Contact("我们是机器人<----q'(^_^)'p---->业务后台开发组", "https://www.glodon.com/", null))
                .version("0.0.1")
                .build();
    }
}

//扫描指定的包
//.apis(RequestHandlerSelectors.basePackage("com.glodon.demo.mybatis")) //扫描的包
//扫描只包含Swagger的注解，这种方式灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

@Configuration
public class SwaggerWebMvcConfigurer implements WebMvcConfigurer {
    // UI界面的配置
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //原始的swagger 如果没有用到原始的可以不用谢
//        registry.addResourceHandler("swagger-ui.html")
//              .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html").
                addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").
                addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

@Controller
@Api(tags = "请求测试API",position = 1)
public class TestController {
}

@GetMapping("/get")
@ResponseBody
@ApiOperation(value = "get请求测试",notes = "get请求",position = 1)
public String get(String name){
    JSONObject json = new JSONObject();
    json.put("requestType","getType");
    json.put("name",name);
    return json.toString();
}

@GetMapping("/get")
@ResponseBody
@ApiOperation(value = "get请求测试",notes = "get请求",position = 1)
public String get(@ApiParam(required = true,value = "name",example = "张三",name = "name") String name){
    JSONObject json = new JSONObject();
    json.put("requestType","getType");
    json.put("name",name);
    return json.toString();
}

@ApiImplicitParams({
    @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public JsonResult login(@RequestParam String mobile, @RequestParam String password,
                        @RequestParam Integer age){
    //...
    return JsonResult.ok(map);
}

@RequestMapping(value = "/ceshia", method = RequestMethod.POST)
@ResponseBody
@ApiOperation(value = "post请求测试",notes = "测试2",position = 2)
@ApiResponses({
    @ApiResponse(code = 200,message = "success",response = RequestCode200.class),
    @ApiResponse(code = 509,message = "服务器校验错误",response = RequestCode509.class),
    @ApiResponse(code = 410,message = "参数错误",response = RequestCode410.class),
    @ApiResponse(code = 510,message = "系统错误",response = RequestCode510.class)
})
public String ceshia(@RequestBody String str){
    JSONObject json = new JSONObject();
    json.put("requestType","postType");
    json.put("body",str);
    return json.toString();
}

package com.github.swaggerplugin.codes;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
 * 200 请求成功
 */
@ApiModel("RequestCode200")
public class RequestCode200 {
    @ApiModelProperty(value = "响应码",name = "messageCode",example = "200")
    private Integer messageCode;
    @ApiModelProperty(value = "返回消息",name = "message",example = "success")
    private String message;
    public Integer getMessageCode() {
        return messageCode;
    }
    public void setMessageCode(Integer messageCode) {
        this.messageCode = messageCode;
    }
    public String getMessage() {
        return message;
    }
    public void setMessage(String message) {
        this.message = message;
    }
}

@GetMapping("/get")
@ResponseBody
@ApiOperation(value = "get请求测试",notes = "get请求",position = 1)
public String get(@ApiParam(required = true,value = "name",example = "张三",name = "name") @PathVariable("name") String name){
    JSONObject json = new JSONObject();
    json.put("requestType","getType");
    json.put("name",name);
    json.put("id","123");
    return json.toString();
}

@GetMapping("/get")
@ResponseBody
@ApiOperation(value = "get请求测试",notes = "get请求",position = 1)
public String get(@ApiParam(required = true,value = "name",example = "张三",name = "name") @RequestParam("name") String name){
    JSONObject json = new JSONObject();
    json.put("requestType","getType");
    json.put("name",name);
    json.put("id","123");
    return json.toString();
}

@ResponseBody
@RequestMapping(method = RequestMethod.GET)
@ApiOperation(position = 2,value = "9.2.获取人工监管配置",notes = "<p><strong>请求的url:</strong></p>\n" +
              "<p>/api/background/config/robotMonitorConfig</p>\n" +
              "<p><strong>返回的成功数据:</strong></p>\n" +
              "<details> \n" +
              "<summary>点击展开查看</summary> \n" +
              "<pre><code class=\"language-json\">{\n" +
              "\n" +
              "    message: &quot;success&quot;,\n" +
              "\n" +
              "    messageCode:&quot;200&quot;,\n" +
              "\n" +
              "    result: [\n" +
              "\n" +
              "        {\n" +
              "\n" +
              "            id: 1,\n" +
              "\n" +
              "            robotId: 18,\n" +
              "\n" +
              "            authStatus: 1,\n" +
              "\n" +
              "            warnStatus: 1,\n" +
              "\n" +
              "            warnRule: \n" +
              "\n" +
              "            {\n" +
              "\n" +
              "                &quot;angry&quot;:1,\n" +
              "\n" +
              "                &quot;unknown&quot;:1,\n" +
              "\n" +
              "                &quot;down&quot;:1,\n" +
              "\n" +
              "                &quot;sameAnswer&quot;:1,\n" +
              "\n" +
              "                &quot;noClick&quot;:1,\n" +
              "\n" +
              "                &quot;keywords&quot;:1\n" +
              "\n" +
              "            },\n" +
              "\n" +
              "            warnKeywords: \n" +
              "\n" +
              "            [\n" +
              "\n" +
              "                &quot;转人工&quot;,\n" +
              "\n" +
              "                &quot;人工回复&quot;\n" +
              "\n" +
              "            ],\n" +
              "\n" +
              "            operatorId: &quot;qubb&quot;,\n" +
              "\n" +
              "            lastModifyTime: 231431341343123\n" +
              "\n" +
              "        }\n" +
              "\n" +
              "    ]\n" +
              "\n" +
              "}\n" +
              "\n" +
              "</code></pre>\n" +
              "</details>\n" +
              "<p><strong>返回的失败数据:</strong></p>\n" +
              "<details> \n" +
              "<summary>点击展开查看</summary> \n" +
              "<pre><code class=\"language-json\">{\n" +
              "    message: &quot;当前用户已退出登陆，请登陆后重试&quot;,\n" +
              "    messageCode:&quot;509&quot;\n" +
              "}\n" +
              "\n" +
              "{\n" +
              "    message: &quot;param robotId error&quot;,\n" +
              "    messageCode:&quot;410&quot;\n" +
              "}\n" +
              "\n" +
              "{\n" +
              "    message: &quot;system error&quot;,\n" +
              "    messageCode:&quot;510&quot;\n" +
              "}\n" +
              "\n" +
              "</code></pre>\n" +
              "</details>\n" +
              "\n" +
              "\n" +
              "\n")
public Object xxx(@ApiParam(value = "机器人ID",defaultValue = "7",required = true) @RequestParam(value = "robotId", required = false) String robotIdStr) {
}

@APiFileInfo("/xxx")

@Controller("/studentController")
@Api(tags = "学生Controller",position = 1)
public class StudentController {
    /**
     * 根据学生ID获取学生信息
     * @param id 学生id
     * @return 返回查询的结果
     */
    @GetMapping("/getStudentById")
    @ApiOperation(value = "根据学生ID获取学生信息",notes = "根据传入的学生ID获取学生信息",position = 1)
    public Object getStudentById(String id){
        return "id="+id;
    }
    /**
     * 添加学生信息
     * @param student 学生的信息
     * @return 返回是否添加成功
     */
    @PostMapping("/addStudent")
    @ApiOperation(value = "添加学生信息",notes = "添加学生信息",position = 1)
    public Object addStudent(@RequestBody Student student){
        return "student="+student.toString();
    }
    /**
     * 含有特殊字段的，添加学生信息
     * @param str 包含两种信息，1：学生信息，2：其他的特殊字段
     * @return 返回是否添加成功
     */
    @PostMapping("/addStudent2")
    @ApiOperation(value = "含有特殊字段的，添加学生信息",notes = "含有特殊字段的，添加学生信息",position = 1)
    public Object addStudentStr(@RequestBody String str){
        return "str="+str;
    }
}

package com.github.swaggerplugin.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
 * @author zhenghui
 * @date 2020年9月17日17:00:25
 * @desc 需要的属性的值
 */
@Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Apicp {
    Class<?> classPath();//对象的原始class地址，必填
    String modelName();//自定义 Model的名字，必填
    String values()[]; //原始对象中已经存在的对象属性名字 ，必填
    String noValues()[] default {} ;//原始对象中不存在的对象属性名字，非必填
    String noValueTypes()[] default {};//原始对象中不存在的对象属性的类型，基本类型例如：String等，非必填
    String noVlaueExplains()[] default {};//自定义变量的参数说明 非必填
}

package com.github.swaggerplugin.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
 * @author zhenghui
 * @date 2020年9月17日17:00:49
 * @desc 排除不需要的属性的值
 */
@Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiIgp {
    Class<?> classPath();//对象的原始class地址，必填
    String modelName();//自定义 Model的名字，必填
    String values()[]; //原始对象中已经存在的对象属性名字 ，必填
    String noValues()[] default {} ;//原始对象中不存在的对象属性名字，非必填
    String noValueTypes()[] default {};//原始对象中不存在的对象属性的类型，基本类型例如：String等，非必填
    String noVlaueExplains()[] default {};//自定义变量的参数说明 非必填
}

/**
 * 针对传值的参数自定义注解
 * @author zhenghui
 * @date 2020年9月13日13:25:18
 * @desc 读取自定义的属性并动态生成model
 */
@Configuration
@Order(-19999)   //plugin加载顺序，默认是最后加载
public class SwaggerModelReader implements ParameterBuilderPlugin {
    @Autowired
    private TypeResolver typeResolver;
    static final Map<String,String> MAPS = new HashMap<>();
    static {
        MAPS.put("byte","java.lang.Byte");
        MAPS.put("short","java.lang.Short");
        MAPS.put("integer","java.lang.Integer");
        MAPS.put("long","java.lang.Long");
        MAPS.put("float","java.lang.Float");
        MAPS.put("double","java.lang.Double");
        MAPS.put("char","java.lang.Character");
        MAPS.put("string","java.lang.String");
        MAPS.put("boolean","java.lang.Boolean");
    }
    //根据用户自定义的类型拿到该类型所在的包的class位置
    static public String getTypePath(String key){
        return key==null || !MAPS.containsKey(key.toLowerCase()) ? null :  MAPS.get(key.toLowerCase());
    }
    @Override
    public void apply(ParameterContext context) {
        ResolvedMethodParameter methodParameter = context.resolvedMethodParameter();
        //自定义的注解
        Optional<ApiIgp> apiIgp = methodParameter.findAnnotation(ApiIgp.class);
        Optional<Apicp> apicp = methodParameter.findAnnotation(Apicp.class);
        if (apiIgp.isPresent() || apicp.isPresent()) {
            Class originClass = null;
            String[] properties = null; //注解传递的参数
            Integer annoType = 0;//注解的类型
            String name = null + "Model" + 1;  //model 名称  //参数名称
            String[] noValues = null;
            String[] noValueTypes = null;
            String[] noVlaueExplains = null;
            //拿到自定义注解传递的参数
            if (apiIgp.isPresent()){
                properties = apiIgp.get().values(); //排除的
                originClass = apiIgp.get().classPath();//原始对象的class
                name = apiIgp.get().modelName() ;  //model 名称  //参数名称
                noValues = apiIgp.get().noValues();
                noValueTypes = apiIgp.get().noValueTypes();
                noVlaueExplains = apiIgp.get().noVlaueExplains();
            }else {
                properties = apicp.get().values(); //需要的
                annoType = 1;
                originClass = apicp.get().classPath();//原始对象的class
                name = apicp.get().modelName() ;//自定义类的名字
                noValues = apicp.get().noValues();
                noValueTypes = apicp.get().noValueTypes();
                noVlaueExplains = apicp.get().noVlaueExplains();
            }
            //生成一个新的类
            Class newClass = createRefModelIgp(properties, noValues, noValueTypes, noVlaueExplains, name, originClass, annoType);
            context.getDocumentationContext()
                    .getAdditionalModels()
                    .add(typeResolver.resolve(newClass));  //向documentContext的Models中添加我们新生成的Class
            context.parameterBuilder()  //修改model参数的ModelRef为我们动态生成的class
                    .parameterType("body")
                    .modelRef(new ModelRef(name))
                    .name(name);
        }
    }
    /**
     *
     * @param properties annoType=1:需要的  annoType=0:排除的
     * @param noValues
     * @param noValueTypes
     * @param noVlaueExplains
     * @param name 创建的mode的名称
     * @param origin
     * @param annoType 注解的类型
     * @return
     */
    private Class createRefModelIgp(String[] properties, String[] noValues, String[] noValueTypes, String[] noVlaueExplains, String name, Class origin, Integer annoType) {
        try {
            //获取原始实体类中所有的变量
            Field[] fields = origin.getDeclaredFields();
            //转换成List集合，方便使用stream流过滤
            List<Field> fieldList = Arrays.asList(fields);
            //把传入的参数也转换成List
            List<String> dealProperties = Arrays.asList(properties);//去掉空格并用逗号分割
            //过滤出来已经存在的
            List<Field> dealFileds = fieldList
                    .stream()
                    .filter(s ->
                            annoType==0 ? (!(dealProperties.contains(s.getName()))) //如果注解的类型是0，说明要取反
                                        : dealProperties.contains(s.getName())
                            ).collect(Collectors.toList());
            //存储不存在的变量
            List<String> noDealFileds = Arrays.asList(noValues);
            List<String> noDealFiledTypes = Arrays.asList(noValueTypes);
            List<String> noDealFiledExplains = Arrays.asList(noVlaueExplains);
            //创建一个类
            ClassPool pool = ClassPool.getDefault();
            CtClass ctClass = pool.makeClass(origin.getPackage().getName()+"."+name);
            //创建对象，并把已有的变量添加进去
            createCtFileds(dealFileds,noDealFileds,noDealFiledTypes,noDealFiledExplains,ctClass,annoType);
            //返回最终的class
            return ctClass.toClass();
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }
    @Override
    public boolean supports(DocumentationType delimiter) {
        return true;
    }
    /**
     * 根据propertys中的值动态生成含有Swagger注解的javaBeen
     *
     * @param dealFileds  原始对象中已经存在的对象属性名字
     * @param noDealFileds  原始对象中不存在的对象属性名字
     * @param noDealFiledTypes 原始对象中不存在的对象属性的类型，八大基本类型例如：dounle等，还有String
     * @param noDealFiledExplains  自定义变量的参数说明
     * @param ctClass 源class
     * @throws CannotCompileException
     * @throws NotFoundException
     * @throws ClassNotFoundException
     */
    public void createCtFileds(List<Field> dealFileds, List<String> noDealFileds, List<String> noDealFiledTypes,List<String> noDealFiledExplains, CtClass ctClass, Integer annoType) {
       //添加原实体类存在的的变量
//        if(annoType==1)
        for (Field field : dealFileds) {
            CtField ctField = null;
            try {
                ctField = new CtField(ClassPool.getDefault().get(field.getType().getName()), field.getName(), ctClass);
            } catch (CannotCompileException e) {
                System.out.println("找不到了1："+e.getMessage());
            } catch (NotFoundException e) {
                System.out.println("找不到了2："+e.getMessage());
            }
            ctField.setModifiers(Modifier.PUBLIC);
            ApiModelProperty annotation = field.getAnnotation(ApiModelProperty.class);
            String apiModelPropertyValue = java.util.Optional.ofNullable(annotation).map(s -> s.value()).orElse("");
            if (StringUtils.isNotBlank(apiModelPropertyValue)) { //添加model属性说明
                ConstPool constPool = ctClass.getClassFile().getConstPool();
                AnnotationsAttribute attr = new AnnotationsAttribute(constPool, AnnotationsAttribute.visibleTag);
                Annotation ann = new Annotation(ApiModelProperty.class.getName(), constPool);
                ann.addMemberValue("value", new StringMemberValue(apiModelPropertyValue,constPool));
                attr.addAnnotation(ann);
                ctField.getFieldInfo().addAttribute(attr);
            }
            try {
                ctClass.addField(ctField);
            } catch (CannotCompileException e) {
                System.out.println("无法添加字段1："+e.getMessage());
            }
        }
        //添加原实体类中不存在的的变量
         for (int i = 0; i < noDealFileds.size(); i++) {
            String valueName = noDealFileds.get(i);//变量名字
            String valueType = noDealFiledTypes.get(i);//变量的类型
            valueType=getTypePath(valueType);
            //根据变量的类型，变量的名字，变量将要在的类 创建一个变量
             CtField ctField = null;
             try {
                 ctField = new CtField(ClassPool.getDefault().get(valueType), valueName, ctClass);
             } catch (CannotCompileException e) {
                 System.out.println("找不到了3："+e.getMessage());
             } catch (NotFoundException e) {
                 System.out.println("找不到了4："+e.getMessage());
             }
             ctField.setModifiers(Modifier.PUBLIC);//设置权限范围是私有的，或者public等
             if(noDealFiledExplains.size()!=0){
                 //参数设置描述
                 String apiModelPropertyValue = (apiModelPropertyValue=noDealFiledExplains.get(i))==null?"无描述":apiModelPropertyValue;//参数描述
                 System.out.println(apiModelPropertyValue);
                 if (StringUtils.isNotBlank(apiModelPropertyValue)) { //添加model属性说明
                     ConstPool constPool = ctClass.getClassFile().getConstPool();
                     AnnotationsAttribute attr = new AnnotationsAttribute(constPool, AnnotationsAttribute.visibleTag);
                     Annotation ann = new Annotation(ApiModelProperty.class.getName(), constPool);
                     ann.addMemberValue("value", new StringMemberValue(apiModelPropertyValue,constPool));
                     attr.addAnnotation(ann);
                     ctField.getFieldInfo().addAttribute(attr);
                 }
             }
             //把此变量添加到类中
             try {
                 ctClass.addField(ctField);
             } catch (CannotCompileException e) {
                 System.out.println("无法添加字段2："+e.getMessage());
             }
         }
    }
}

/**
* 含有特殊字段的，添加学生信息
* @param str 包含两种信息，1：学生信息，2：其他的特殊字段
* @return 返回是否添加成功
*/
@PostMapping("/addStudent2")
@ApiOperation(value = "含有特殊字段的，添加学生信息",notes = "含有特殊字段的，添加学生信息",position = 1)
public Object addStudentStr(@Apicp(values = {"Id","name"}, //Student类中已经存在的
                                   modelName = "addStudent2", //自定义Model的名字，也是要生成的类名
                                   classPath = Student.class, //原始的类
                                   noValues = {"lala","haha","xixi"}, //原始的类中没有的参数
                                   noValueTypes = {"string","integer","double"},//原始的类中没有的参数的类型
                                   noVlaueExplains = {"啦啦","哈哈","嘻嘻"})//原始的类中没有的参数的描述
                            @RequestBody String str){
    return "str="+str;
}

[
    {
        "id":62564697,
        "slug":"09c7db472fa6",
        "title":"Java的SPI机制",
        "view_count":42,
        "user":{
            "id":12724216,
            "nickname":"bdqfork",
            "slug":"a2329f464833",
            "avatar":"https://upload.jianshu.io/users/upload_avatars/12724216/6f2b07cc-e9bf-440d-a6ad-49fbaa3b49ce.jpg"
        }
    },
    {
        "id":62564140,
        "slug":"ec3bd614dcb0",
        "title":"SLF4J日志级别以及使用场景",
        "view_count":381,
        "user":{
            "id":12724216,
            "nickname":"bdqfork",
            "slug":"a2329f464833",
            "avatar":"https://upload.jianshu.io/users/upload_avatars/12724216/6f2b07cc-e9bf-440d-a6ad-49fbaa3b49ce.jpg"
        }
    }
]

{
    "messageCode": 410,
    "message": "姓名不能为空"
}

{
    "messageCode": 509,
    "message": "姓名长度不超过15"
}
{
    "messageCode": 509,
    "message": "姓名数量不能超过15个"
}
{
    "messageCode": 509,
    "message": "姓名已存在"
}
{
    "messageCode": 509,
    "message": "存在姓名，暂不可新增"
}

{
    "messageCode": 510,
    "message": "system error"
}

/**
     * 根据学生ID获取学生信息
     * @param id 学生id
     * @return 返回查询的结果
     */
    @GetMapping("/getStudentById")
    @ApiOperation(value = "根据学生ID获取学生信息",notes = "" +
            "[\n" +
            "    {\n" +
            "        \"id\":62564697,\n" +
            "        \"slug\":\"09c7db472fa6\",\n" +
            "        \"title\":\"Java的SPI机制\",\n" +
            "        \"view_count\":42,\n" +
            "        \"user\":{\n" +
            "            \"id\":12724216,\n" +
            "            \"nickname\":\"bdqfork\",\n" +
            "            \"slug\":\"a2329f464833\",\n" +
            "            \"avatar\":\"https://upload.jianshu.io/users/upload_avatars/12724216/6f2b07cc-e9bf-440d-a6ad-49fbaa3b49ce.jpg\"\n" +
            "        }\n" +
            "    },\n" +
            "    {\n" +
            "        \"id\":62564140,\n" +
            "        \"slug\":\"ec3bd614dcb0\",\n" +
            "        \"title\":\"SLF4J日志级别以及使用场景\",\n" +
            "        \"view_count\":381,\n" +
            "        \"user\":{\n" +
            "            \"id\":12724216,\n" +
            "            \"nickname\":\"bdqfork\",\n" +
            "            \"slug\":\"a2329f464833\",\n" +
            "            \"avatar\":\"https://upload.jianshu.io/users/upload_avatars/12724216/6f2b07cc-e9bf-440d-a6ad-49fbaa3b49ce.jpg\"\n" +
            "        }\n" +
            "    }\n" +
            "]",position = 1)
    public Object getStudentById(String id){
        return "id="+id;
    }

<!--makdown to html-->
<dependency>
    <groupId>com.vladsch.flexmark</groupId>
    <artifactId>flexmark-all</artifactId>
    <version>0.50.42</version>
</dependency>

//makdown语法转换成html语法的工具
MutableDataSet options = new MutableDataSet();
Parser parser = Parser.builder(options).build();
HtmlRenderer renderer = HtmlRenderer.builder(options).build();
// You can re-use parser and renderer instances
Node document = parser.parse(mdBody.toString());
//转换成html
String html = renderer.render(document);  // "<p>This is <em>Sparta</em></p>\n"

/**
     * 根据学生ID获取学生信息
     * @param id 学生id
     * @return 返回查询的结果
     */
@GetMapping("/getStudentById")
@ApiOperation(value = "根据学生ID获取学生信息",notes = "" +
              "<pre><code class=\"language-json\">[\n" +
              "    {\n" +
              "        &quot;id&quot;:62564697,\n" +
              "        &quot;slug&quot;:&quot;09c7db472fa6&quot;,\n" +
              "        &quot;title&quot;:&quot;Java的SPI机制&quot;,\n" +
              "        &quot;view_count&quot;:42,\n" +
              "        &quot;user&quot;:{\n" +
              "            &quot;id&quot;:12724216,\n" +
              "            &quot;nickname&quot;:&quot;bdqfork&quot;,\n" +
              "            &quot;slug&quot;:&quot;a2329f464833&quot;,\n" +
              "            &quot;avatar&quot;:&quot;https://upload.jianshu.io/users/upload_avatars/12724216/6f2b07cc-e9bf-440d-a6ad-49fbaa3b49ce.jpg&quot;\n" +
              "        }\n" +
              "    },\n" +
              "    {\n" +
              "        &quot;id&quot;:62564140,\n" +
              "        &quot;slug&quot;:&quot;ec3bd614dcb0&quot;,\n" +
              "        &quot;title&quot;:&quot;SLF4J日志级别以及使用场景&quot;,\n" +
              "        &quot;view_count&quot;:381,\n" +
              "        &quot;user&quot;:{\n" +
              "            &quot;id&quot;:12724216,\n" +
              "            &quot;nickname&quot;:&quot;bdqfork&quot;,\n" +
              "            &quot;slug&quot;:&quot;a2329f464833&quot;,\n" +
              "            &quot;avatar&quot;:&quot;https://upload.jianshu.io/users/upload_avatars/12724216/6f2b07cc-e9bf-440d-a6ad-49fbaa3b49ce.jpg&quot;\n" +
              "        }\n" +
              "    }\n" +
              "]\n" +
              "</code></pre>\n" +
              "\n" +
              "\n" +
              "",position = 1)
public Object getStudentById(String id){
    return "id="+id;
}

public class MdToHtml {
    /**
     * @param md makdown语法
     * @return html语法
     */
    public final static String makdownToHtml(String md) {
        StringBuilder mdBody = new StringBuilder();
        //遍历传递过来的md，查找到```xxx开头的 一直到```结尾的
        for (int i = 0; i < md.length() ; i++) {
            //重新构造一个```json  ```代码块
            StringBuilder newCodeBody = new StringBuilder();
            newCodeBody.append("\n\n");
            newCodeBody.append("<details> \n");
            newCodeBody.append("\n");
            newCodeBody.append("<summary>点击展开查看</summary> \n");
            //code body start  ```开始
            if(md.charAt(i)=='`' && md.charAt(i+1)=='`' && md.charAt(i+2)=='`'){
                String temp = md.substring(i+3);//开始分割```
                int strIndex = findStrIndex(temp);//查找```之后的代码类型例如：```java，```json等，查找结束的位置
                String codeType = md.substring(i + 3, i + 3 + strIndex);//保留代码的类型
                newCodeBody.append("\n```"+codeType+"\n");//重新合并类型
                //从代码块的类型开始例如：```json之后开始  +1：代码块类型之后的回车   ```结束
                for (int j = i+3+strIndex+1; j < md.length() ; j++) {
                    //code body end  遇到```代码块结束了
                    if(md.charAt(j)=='`' && md.charAt(j+1)=='`' && md.charAt(j+2)=='`'){
                        i=j+3; //让i跳过去```json  到```中的代码
                        //追加上```代码块的结尾
                        newCodeBody.append("\n```\n");
                        //追加上折叠代码块的结尾
                        newCodeBody.append("\n");
                        newCodeBody.append("</details>");
                        newCodeBody.append("\n");
                        break;//跳出本次循环 代表```json  此代码块 ```结束了
                    }else{
                        //组合code body内的代码
                        newCodeBody.append(md.charAt(j));
                    }
                }
                //代码整合结束后，把整合后的代码追加到makdown的Body中
                mdBody.append(newCodeBody.toString());
            }else{
                //其他的代码一律直接追加到makdown body中
                mdBody.append(md.charAt(i));
            }
        }
        //makdown语法转换成html语法的工具
        MutableDataSet options = new MutableDataSet();
        Parser parser = Parser.builder(options).build();
        HtmlRenderer renderer = HtmlRenderer.builder(options).build();
        // You can re-use parser and renderer instances
        Node document = parser.parse(mdBody.toString());
        //转换成html
        String html = renderer.render(document);  // "<p>This is <em>Sparta</em></p>\n"
        return html;
    }
    static private int findStrIndex(String str){
        int sum = 0;
        for (int i = 0; i <str.length() ; i++) {
            if(str.charAt(i)=='\n')
                return sum++;
            else
                sum++;
        }
        return -1;
    }
}

package com.github.swaggerplugin.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface APiFileInfo {
    String value() default "";//url,flag 在某文档中存放的一个标志
}

/**
 * 针对方法自定义注解
 * @author zhenghui
 * @date 2020年9月13日13:25:18
 * @desc 读取自定义的属性并动态生成model
 * OperationBuilderPlugin：对方法起作用
 */
@Component
@Order(1)
public class OperationPositionBulderPlugin implements OperationBuilderPlugin {
    @Autowired
    private TypeResolver typeResolver;
    static Map<String,Map<Integer, APiFileInfoBean>> apiFileInfoMaps = null;
    public static String swaggerMdPaths  = "src/main/resources/md";
    private static boolean flag = false;
    @Value("${swagger.md.paths}")
    private void setSwaggerMdPaths(String swaggerMdPaths){
        OperationPositionBulderPlugin.swaggerMdPaths = swaggerMdPaths;
    }
    // 解析文件
    public OperationPositionBulderPlugin() {
        String[] paths = swaggerMdPaths.split(",");
        System.out.println("开始解析文件了------------>>>>");
        System.out.println("文件地址："+Arrays.toString(paths));
//        Map<String,Map<Integer,APiFileInfoBean>> apiFileInfoMaps = initFile(new String[]{"src/main/resources/md/md.md"});
        if(apiFileInfoMaps==null) {
            apiFileInfoMaps = ReadFromFile.initFileOrDirectory(paths);
            flag=apiFileInfoMaps==null?false:true;
        }
    }
    @Override
    public void apply(OperationContext context) {
        if(flag){
            System.out.println("有文件，加载："+flag);
        //1、查找是否定义了说明文件的所在位置
//        Optional<ApiFIleURI> apiFIleURIOptional = context.findAnnotation(ApiFIleURI.class);
//        if(apiFIleURIOptional.isPresent()){
//            String mdFileURIs[] = apiFIleURIOptional.get().vlaue();//拿到文件的所在位置
            //2、查找APiFileInfo注解，
            Optional<APiFileInfo> apiFileInfoOptional = context.findAnnotation(APiFileInfo.class);
            if (apiFileInfoOptional.isPresent()) {
                String flag = null;//获取URL（URL作用是定位到）
                System.out.println("apiFileInfoOptional--->"+apiFileInfoOptional.get().value());
                flag = apiFileInfoOptional.get().value();//获取标志，标志：在文件中所在的位置
                //构建消息
                context.operationBuilder()
                        .responseMessages(buildResponseMessage(flag, apiFileInfoMaps));
            }
//        }
        }else {
            System.out.println("没有文件，不加载");
        }
    }
    /**
     * 构造ResponseMessage
     * @param flag 该消息说明描述的文本所在的位置
     * @param apiFileInfoMaps
     * @return
     */
    private Set<ResponseMessage> buildResponseMessage(String flag, Map<String, Map<Integer,APiFileInfoBean>> apiFileInfoMaps) {
        Map<Integer,APiFileInfoBean> aPiFileInfoBean = apiFileInfoMaps.get(flag);
        Set<ResponseMessage> set = new HashSet<>();
        ResponseMessage responseMessage = null;
        if(aPiFileInfoBean!=null)
        for (Integer code : aPiFileInfoBean.keySet()) {
            APiFileInfoBean fileInfoBean = aPiFileInfoBean.get(code);
            responseMessage = new ResponseMessageBuilder()
                                    .code(code)
                                    .message(MdToHtml.makdownToHtml(fileInfoBean.getMessage()))
                                    .responseModel(new ModelRef("UpdateRobotModel"))
                                    .build();
//            responseMessage = new ResponseMessage(code, MdToHtml.makdownToHtml(fileInfoBean.getMessage()), null,new HashMap<>(),new LinkedList<>());
            set.add(responseMessage);
        }
        return set;
    }
    @Override
    public boolean supports(DocumentationType delimiter) {
        return true;
    }
}

package com.github.swaggerplugin.util;
import com.github.swaggerplugin.bean.APiFileInfoBean;
import java.io.*;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
//文件解析工具
public class ReadFromFile {
    /**
     * 解析文件
     * @param mdFileURIs
     * @return
     */
    public static Map<String, Map<Integer, APiFileInfoBean>> initFileOrDirectory(String[] mdFileURIs) {
        Map<String, Map<Integer,APiFileInfoBean>> map = new HashMap<>();
        for (String fileURIs : mdFileURIs) {
            File file = new File(fileURIs);
            //是文件夹
            if(file!=null && !file.isFile()){
                //解析目录中的文件
                initDirectory(map,file);
                //是文件
            }else if(file!=null && file.isFile()){
                //解析单个文件
                initFile(map,file);
            }
        }
        return map.size()<=0?null:map;
    }
    /**
     * 解析文件
     * @param map
     * @param file
     */
    private static void initFile(Map<String, Map<Integer,APiFileInfoBean>> map, File file) {
        List<String> list = ReadFileDataToList(file);//文件内容读取到List中，方便之后解析和操作
        int start = 0;//一个api的描述的开始
        int end = 0;//一个api的描述的结束
        //操作每一行数据
        for (int i = 0; i < list.size(); i++) {
            String dataLine = list.get(i);
//            System.out.println("dataLine-->"+dataLine);
            //开头是# URL:号的 代表是一个URL的开始
            if(dataLine.startsWith("# URL:")){
                start = i;
//                System.out.println("#-->"+dataLine);
                //找到当前这个API描述的 结束的位置
                for (int j = i+1;j<list.size();j++){
                    String dataLine_start = list.get(j);
                    if(dataLine_start.startsWith("# URL:")) {
                        System.out.println("当前API的起始位置："+i+"-->"+(j-1));
                        end = j-1;//记录结束的位置
                        i=j-1;//i位置跳过整个流程
                        break;
                    }
                }
                //针对这个区间进行处理
                disposeInterval(start,end,list,map);
            }
        }
        //处理最后一组API的数据
//        System.out.println(start+"-->"+(list.size()));
        System.out.println("当前API的起始位置："+start+"-->"+(list.size()));
        //针对这个区间进行处理
        disposeInterval(start,list.size(),list,map);
    }
    /**
     * 处理这个区间的数据
     * @param start
     * @param end
     * @param list
     * @param map
     */
    private static void disposeInterval(int start, int end, List<String> list, Map<String,Map<Integer,APiFileInfoBean>> map) {
//        System.out.println("正在处理--------------------------");
        int code_start = 0;
        int code_end = 0;
        String flag = null;
        for (int index = start; index < end ; index++) {
            String s = list.get(index);
            if(s.startsWith("# URL:")){
                flag = s.substring(6, s.length()).replace(" ","");
            }
            //找出每个code的数据的开始和结束
            if(s.replace(" ","").endsWith("---") && s.replace(" ","").equals("---")){
                //记录开始的位置
                code_start = index+1+1;
                for (int i = index+1; i < end; i++) {
                    s=list.get(i);
                    //结束
                    if(s.replace(" ","").endsWith("---") && s.replace(" ","").equals("---")) {
                        //记录结束位置
                        code_end = i-1;
                        //跳过这个区间的代码
                        index = i-1;
                        System.out.println("code起始位置："+code_start+"--->"+code_end);
                        //处理这个code的区间的数据
                        disposeCodeInterval(flag,code_start,code_end,list,map);
                        break;
                    }
                }
            }
        }
    }
    /**
     * 处理code区间的数据
     * @param flag
     * @param code_start
     * @param code_end
     * @param list
     * @param map
     */
    private static void disposeCodeInterval(String flag, int code_start, int code_end, List<String> list, Map<String, Map<Integer, APiFileInfoBean>> map) {
        APiFileInfoBean aPiFileInfoBean = new APiFileInfoBean();
        Map<Integer,APiFileInfoBean> fileInfoBeanMap = new HashMap<>();
        StringBuilder sb = new StringBuilder();
//        System.out.println("正在处理--------------------------");
        for (int index = code_start; index <= code_end ; index++) {
            String s = list.get(index);
            if(s.startsWith("code:")){
                String code = s.substring(5, s.length());
//                System.out.println(code);
                try {//防止code不是数字
                    aPiFileInfoBean.setCode(Integer.valueOf(code.replace(" ","")));
                }catch (Exception e){
                    e.fillInStackTrace();
                }
            }else if(s!=null && !(s.replace(" ","")).equals("") ){
//                String md = list.get(index);
                //code body start  ```开始
                if(s.charAt(0)=='`' && s.charAt(1)=='`' && s.charAt(2)=='`'){
//                    System.out.println("哈哈，找到了："+md);
                    sb.append(s+"\n");
                    for (int i = index+1; i < list.size() ; i++) {
                        s = list.get(i);
//                        System.out.println("内容："+md);
                        sb.append(list.get(i)+"\n");
                        if(s!=null && !(s.replace(" ","").equals("")) &&s.charAt(0)=='`' && s.charAt(1)=='`' && s.charAt(2)=='`'){
                            index=i;
                            break;
                        }
                    }
                }else{
//                System.out.println(list.get(index));
                    sb.append(s+"\n");
                }
            }else{
//                System.out.println(list.get(index));
                sb.append(list.get(index)+"\n");
            }
        }
//            System.out.println("code起始位置："+code_end+"--->"+end);
        aPiFileInfoBean.setMessage(sb.toString());
//        System.out.println("处理结束--------------------------");
//        System.out.println(aPiFileInfoBean);
        if(flag!=null && !flag.equals("") && aPiFileInfoBean!=null){
            fileInfoBeanMap.put(aPiFileInfoBean.getCode(),aPiFileInfoBean);
            Map<Integer, APiFileInfoBean> fileInfoBeanMap1 = map.get(flag);
            if(fileInfoBeanMap1!=null)
                fileInfoBeanMap.putAll(fileInfoBeanMap1);
            map.put(flag,fileInfoBeanMap);
        }
    }
    /**
     * 解析目录中所有的文件
     * @param map
     * @param file
     */
    private static void initDirectory(Map<String, Map<Integer,APiFileInfoBean>> map, File file) {
        //解析目录
        //1、查询
        File[] files = file.listFiles();
        for (File fi : files) {
            if(!fi.isFile()){
                System.out.println(fi+"-->是目录");
                initDirectory(map,fi);//处理目录
            }else{
                System.out.println(fi+"-->是文件");
                initFile(map,fi);//处理文件
            }
        }
        System.out.println("---");
        //解析单个文件
//        initFile(map,file);
    }
    /**
     * 读取单个文件中的内容
     * @param file
     * @return
     */
    public static List<String> ReadFileDataToList( File file) {
        FileInputStream fis = null;
        InputStreamReader isr = null;
        BufferedReader br = null;
        List<String> list = new ArrayList<>();
        try {
            fis = new FileInputStream(file);
            isr = new InputStreamReader(fis);
            br = new BufferedReader(isr);
            String dataLine = null;
//            int i = 0;
            while((dataLine = br.readLine()) != null) {
//                System.out.println(i+" --->"+dataLine);
                list.add(dataLine);
//                i++;
            }
        } catch (FileNotFoundException e) {
            System.out.println("解析文件不存在"+e.getMessage());
        } catch (IOException e) {
            System.out.println("解析文件出错了："+e.getMessage());
        } finally {
            try {
                if(br != null) br.close();
                if(isr != null) isr.close();
                if(fis != null) fis.close();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return list;
    }
}

# URL:/getStudentById
---
code:200
**这是200响应码的描述**
```json
 [
    {
        "id":62564697,
        "slug":"09c7db472fa6",
        "title":"Java的SPI机制",
        "view_count":42,
        "user":{
            "id":12724216,
            "nickname":"bdqfork",
            "slug":"a2329f464833",
            "avatar":"https://upload.jianshu.io/users/upload_avatars/12724216/6f2b07cc-e9bf-440d-a6ad-49fbaa3b49ce.jpg"
        }
    },
    {
        "id":62564140,
        "slug":"ec3bd614dcb0",
        "title":"SLF4J日志级别以及使用场景",
        "view_count":381,
        "user":{
            "id":12724216,
            "nickname":"bdqfork",
            "slug":"a2329f464833",
            "avatar":"https://upload.jianshu.io/users/upload_avatars/12724216/6f2b07cc-e9bf-440d-a6ad-49fbaa3b49ce.jpg"
        }
    }
]
```
---
code:410
### 517状态码的描述
```json
{
    "messageCode": 410,
    "message": "姓名不能为空"
}
```
---
code:509
#### 510测试描述
```json
{
    "messageCode": 509,
    "message": "姓名长度不超过15"
}
{
    "messageCode": 509,
    "message": "姓名数量不能超过15个"
}
{
    "messageCode": 509,
    "message": "姓名已存在"
}
{
    "messageCode": 509,
    "message": "存在姓名，暂不可新增"
}
```
---

/**
     * 根据学生ID获取学生信息
     * @param id 学生id
     * @return 返回查询的结果
     */
@GetMapping("/getStudentById")
@ApiOperation(value = "根据学生ID获取学生信息",notes = "",position = 1)
@APiFileInfo("/getStudentById")
public Object getStudentById(String id){
    return "id="+id;
}

return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
@Documented
public @interface Order {
    int value() default 2147483647;
}

public interface Ordered {
    int HIGHEST_PRECEDENCE = -2147483648;
    int LOWEST_PRECEDENCE = 2147483647;
    int getOrder();
}

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
//@Order(1)
public class OperationPositionBulderPlugin implements OperationBuilderPlugin {
    .........忽略代码
}

@Component
//@Order(Ordered.HIGHEST_PRECEDENCE)
@Order(999999)
public class OperationPositionBulderPlugin implements OperationBuilderPlugin {
    ........
}

@Component
@Order(1)
public class BlackPersion implements CommandLineRunner {
    @Override
    public void run(String... args) throws Exception {
        System.out.println("----BlackPersion----");
    }
}
@Component
@Order(0)
public class YellowPersion implements CommandLineRunner {
    @Override
    public void run(String... args) throws Exception {
        System.out.println("----YellowPersion----");
    }
}

----YellowPersion----
----BlackPersion----