jetplugins / apidocx

Generate API documents to any place: YApi, RAP2, Eolink, etc.
https://plugins.jetbrains.com/plugin/17425-apidocx/
Apache License 2.0
177 stars 39 forks source link

feat: 支持接口/实体类 @see引用派生类获取扁平化字段列表信息 #15

Closed BOFA1ex closed 2 years ago

BOFA1ex commented 2 years ago

存在以下场景, 返参类型是JobDTO. 其字段content接口响应结果为向下转型后的派生类对象. 因此接口文档中关于content@object的描述需要涵盖NormalJobContentDTO/WorkflowJobContentDTO内的所有字段.

public class JobDTO {
    /**
     * 任务实例内容
     * [note]返回对象为向下转型后的派生类
     */
    private JobContentDTO content;
}

/**
 * @see NormalJobContentDTO
 * @see WorkflowJobContentDTO
 */
public interface JobContentDTO {

}

public class NormalJobContentDTO implements JobContentDTO {
    /**
     * 任务实例#field0
     */
    private Integer field0;
}

public class WorkflowJobContentDTO implements JobContentDTO {
    /**
     * 工作流实例#子任务DAG
     */
    private String dags;
}

接口文档大致如下 image

lkqm commented 2 years ago

有两个建议的地方,你看看:

  1. see解析似乎再字段上更合理,而不是再接口上
  2. see短名称解析优化,可以参考link解析方式
BOFA1ex commented 2 years ago

@see解析似乎再字段上更合理,而不是再接口上

我这个考虑过, 最终考虑声明在类的javadoc, 具体原因如下: JobDTO类里有JobContentDTO字段, 不代表其他类就不会引用JobContentDTO. 如果你声明@see在字段上, 就需要对多处字段进行多次声明.

@see 短名称解析优化, 可以参考link解析方式

这个我在pr #18 里已经给出review comment, 这里就不赘述了.