{"id":18600623,"url":"https://github.com/houbb/idoc","last_synced_at":"2025-04-10T18:31:29.062Z","repository":{"id":57720083,"uuid":"170058072","full_name":"houbb/idoc","owner":"houbb","description":"🌾Generate doc for java maven project.(java 项目自动生成文档)","archived":false,"fork":false,"pushed_at":"2021-10-14T15:22:04.000Z","size":294,"stargazers_count":51,"open_issues_count":5,"forks_count":19,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-25T03:01:37.387Z","etag":null,"topics":["doc","doc-generate","java-doc"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/houbb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-11T02:53:23.000Z","updated_at":"2025-02-07T15:57:28.000Z","dependencies_parsed_at":"2022-09-26T21:41:13.739Z","dependency_job_id":null,"html_url":"https://github.com/houbb/idoc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/houbb%2Fidoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/houbb%2Fidoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/houbb%2Fidoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/houbb%2Fidoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/houbb","download_url":"https://codeload.github.com/houbb/idoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248271750,"owners_count":21075800,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["doc","doc-generate","java-doc"],"created_at":"2024-11-07T02:04:45.394Z","updated_at":"2025-04-10T18:31:28.051Z","avatar_url":"https://github.com/houbb.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 写文档\n\n作为一名开发者，每个人都要写代码。\n\n工作中，几乎每一位开发者都要写文档。\n\n因为工作是人和人的协作，产品要写需求文档，开发要写详细设计文档，接口文档。\n\n可是，作为一个懒人，平时最讨厌的一件事情就是写文档。\n\n![文档](文档.png)\n\n写文档最令我不爽的地方是在于**代码备注要改一遍，然后文档再改一遍。**\n\n所有重复的劳作，都是对于我们宝贵摸鱼时间的最大浪费。\n\n于是，我就常常想，能不能只写一遍呢？\n\n# i-doc 项目简介\n\n[idoc](https://github.com/houbb/idoc) 为 java 项目生成项目文档。\n\n基于原生的 java 注释，尽可能的生成简介的文档。用户可以自定义自己的模板，生成自己需要的文档。\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.houbb/idoc/badge.svg)](http://mvnrepository.com/artifact/com.github.houbb/idoc)\n[![Build Status](https://www.travis-ci.org/houbb/idoc.svg?branch=master)](https://www.travis-ci.org/houbb/idoc?branch=master)\n[![Coverage Status](https://coveralls.io/repos/github/houbb/idoc/badge.svg?branch=master)](https://coveralls.io/github/houbb/idoc?branch=master)\n\n实现原理：基于 maven 插件，类似于 javadoc。可以更加灵活，允许用户自定义。\n\n## 特性\n\n- 基于 maven 项目生成包含大部分信息的元数据\n\n- 默认支持 markdown 简化文档的生成，支持自定义模板\n\n- 支持用户自定义文档生成器\n\n- 支持用户自定生成文档的类过滤器\n\n- 添加字段类型别名，支持用户自定义\n\n# 变更日志\n\n\u003e [变更日志](doc/CHANGELOG.md)\n\n# 快速入门\n\n## 需要 \n\njdk1.8+\n\nmaven 3.x+\n\n## maven 引入\n\n使用 maven 引入当前 idoc 插件。\n\n```xml\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003ecom.github.houbb\u003c/groupId\u003e\n            \u003cartifactId\u003eidoc-core\u003c/artifactId\u003e\n            \u003cversion\u003e0.3.0\u003c/version\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\n## 测试对象的创建\n\n为了演示文档，我们创建了一个 Address 对象。\n\n```java\npackage com.github.houbb.idoc.test.model;\n\n/**\n * 地址\n * @author binbin.hou\n * @since 0.0.1\n */\npublic class Address {\n\n    /**\n     * 城市\n     */\n    private String country;\n\n    /**\n     * 街道\n     */\n    private String street;\n\n    public String getCountry() {\n        return country;\n    }\n\n    public void setCountry(String country) {\n        this.country = country;\n    }\n\n    public String getStreet() {\n        return street;\n    }\n\n    public void setStreet(String street) {\n        this.street = street;\n    }\n}\n\n```\n\n## 执行插件\n\n```\nmvn com.github.houbb:idoc-core:0.3.0:idoc\n```\n\n## 命令行日志信息\n\n```\n[INFO] ------------------------------------ Start generate doc\n[INFO] 共计 【1】 个文件待处理，请耐心等待。进度如下：\n==================================================================================================== 100%\n[INFO] Generator doc with docGenerator: com.github.houbb.idoc.core.api.generator.ConsoleDocGenerator\n[INFO] ------------------------------------ 文档信息如下：\n\n[类名] com.github.houbb.idoc.test.model.Address\n[类信息] {\"comment\":\"地址\",\"docAnnotationList\":[],\"docFieldList\":[{\"comment\":\"城市\",\"name\":\"country\",\"type\":\"java.lang.String\"},{\"comment\":\"街道\",\"name\":\"street\",\"type\":\"java.lang.String\"}],\"docMethodList\":[{\"docMethodParameterList\":[],\"docMethodReturn\":{\"fullName\":\"java.lang.String\",\"name\":\"String\",\"packageName\":\"java.lang\"},\"docTagList\":[],\"exceptionList\":[],\"modifiers\":[\"public\"],\"name\":\"getCountry\",\"seeList\":[],\"signature\":\"getCountry()\"},{\"docMethodParameterList\":[{\"docAnnotationList\":[],\"name\":\"country\",\"type\":\"java.lang.String\"}],\"docMethodReturn\":{},\"docTagList\":[],\"exceptionList\":[],\"modifiers\":[\"public\"],\"name\":\"setCountry\",\"seeList\":[],\"signature\":\"setCountry(country)\"},{\"docMethodParameterList\":[],\"docMethodReturn\":{\"fullName\":\"java.lang.String\",\"name\":\"String\",\"packageName\":\"java.lang\"},\"docTagList\":[],\"exceptionList\":[],\"modifiers\":[\"public\"],\"name\":\"getStreet\",\"seeList\":[],\"signature\":\"getStreet()\"},{\"docMethodParameterList\":[{\"docAnnotationList\":[],\"name\":\"street\",\"type\":\"java.lang.String\"}],\"docMethodReturn\":{},\"docTagList\":[],\"exceptionList\":[],\"modifiers\":[\"public\"],\"name\":\"setStreet\",\"seeList\":[],\"signature\":\"setStreet(street)\"}],\"docTagList\":[{\"lineNum\":5,\"name\":\"author\",\"parameters\":[\"binbin.hou\"],\"value\":\"binbin.hou\"},{\"lineNum\":6,\"name\":\"since\",\"parameters\":[\"0.0.1\"],\"value\":\"0.0.1\"}],\"fullName\":\"com.github.houbb.idoc.test.model.Address\",\"modifiers\":[\"public\"],\"name\":\"Address\",\"packageName\":\"com.github.houbb.idoc.test.model\"}\n\n[INFO] ------------------------------------ Finish generate doc\n```\n\n## 更多生成方式\n\n当然，你可以发现这里只是把元数据进行输出到控台，意义不大。\n\n我们可以根据需求，自定义实现生成类。\n\n比如下面的方式，可以使用内置的 `MarkdownDocGenerator` 输出到 markdown 文件。\n\n```xml\n\u003cplugin\u003e\n    \u003cgroupId\u003ecom.github.houbb\u003c/groupId\u003e\n    \u003cartifactId\u003eidoc-core\u003c/artifactId\u003e\n    \u003cversion\u003e0.3.0\u003c/version\u003e\n    \u003cconfiguration\u003e\n        \u003cgenerates\u003e\n            \u003cgenerate\u003ecom.github.houbb.idoc.ftl.api.generator.MarkdownDocGenerator\u003c/generate\u003e\n        \u003c/generates\u003e\n    \u003c/configuration\u003e\n    \u003cdependencies\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003ecom.github.houbb\u003c/groupId\u003e\n            \u003cartifactId\u003eidoc-ftl\u003c/artifactId\u003e\n            \u003cversion\u003e0.3.0\u003c/version\u003e\n        \u003c/dependency\u003e\n    \u003c/dependencies\u003e\n\u003c/plugin\u003e\n```\n\n效果可以参考：\n\n\u003e [heaven 文档目录](https://github.com/houbb/heaven/blob/master/doc/gen/heaven-%E7%B4%A2%E5%BC%95.md)\n\nps: [heaven](https://github.com/houbb/heaven) 项目是个人整理了多年的工具包，几百个类，手写文档估计要很久。\n\n# 设计初衷\n\n## 节约时间\n\nJava 文档一直是一个大问题。\n\n很多项目不写文档，即使写文档，对于开发人员来说也是非常痛苦的。\n\n不写文档的缺点自不用多少，手动写文档的缺点也显而易见：\n\n1. 非常浪费时间，而且会出错。\n\n2. 无法保证及时更新。代码已经变了，但是文档还要同步修改。需要强制人来维护这一种一致性。这很难。\n\n## 为什么不是 swagger-ui\n\njava 的文档有几类：\n\n1. jdk 自带的 doc 生成。这个以前实践给别人用过，别人用 C#，看到 java 的默认文档感觉很痛苦。\n\n就算是我们 java 开发者，也很讨厌看 jdk 的文档。看着不美观，也很累。\n\n2. swagger-ui 是基于 java 注解的文档生成工具。相对而言比较优雅，也非常强大。\n\n但是缺点也是有的。开发人员要写 jdk 原来的注释+注解。注解太多，导致写起来也很痛苦，大部分开发者后来还是选择了放弃。\n\n那么问题来了？我们怎么办才能尽可能的让开发人员，和文档阅读人员都乐于接受呢？\n\njdk 自带的 doc 就是基于 maven 插件的，本项目也是。\n\n区别如下：\n\n1. 尽可能的保证和 Java 原生注释一致，让开发者很容易就可以使用。\n\n2. 尽可能的信息全面，但是文档简洁。让文档的阅读者享受到等同于手写文档的体验。\n\n3. 将信息的获取和生成区分开。方便用户自己定义自己的输出方式。\n\n# 参数配置说明\n\n为了更加灵活的实现文档的生成和文档元数据的生成，提供如下参数\n\n## 插件配置属性简介\n\n| 属性 | 是否必填 | 说明 | 默认值 | 备注 |\n|:----|:----|:----|:----|:----|\n| encoding | 否 | 项目编码 | UTF-8 | |\n| includes | 否 | 元数据包含的文件信息 | `**\\/*.java` | 默认扫描所有 java 文件 |\n| excludes | 否 | 元数据排除的文件信息 | 无 | 默认不排除 |\n| isOverwriteWhenExists | 否 | 文档存在时是否覆盖 | true |  | \n| isAllInOne | 否 | 所有类信息是否生成单个文档 | true | 命令行文档生成器，此属性无意义。 |\n| generates | 否 | 文档生成类 | 命令行文档生成信息 |  可以同时指定多个。类名全称。用户自定义参见 `com.github.houbb.idoc.api.core.genenrator.IDocGenerator` |\n| generateFilters | 否 | 文档生成类过滤器 | 无 |  可以同时指定多个。类名全称。用户自定义参见 `com.github.houbb.idoc.api.core.filter.IDocGenerateFilter` |\n| targetDir | 否 | 生成目标文件目录 | 无 | 自定义指定文档生成的文件夹 |\n\n## isAllInOne\n\n简单的文档，建议直接生成在一个文件。\n\n如果较为复杂，则可以设为 false，则会按照\n\n## generates 相关问题\n\n默认的命令行文档，主要用于演示和信息查看，不具有实际意义。\n\n建议引入 `idoc-ftl` 模块，使用 `MarkdownDocGenerator` 生成器。\n\n可以同时指定多个。\n\n可引入 `idoc-api` 自行定义。\n\n## generateFilters 建议\n\n实际的文档，主要关心定义的方法。\n\n我们可以针对 DocClass 的包名，过滤只生成 Service 方法文档。\n\n如果是在以前的基础上，则可以加上 `@since` `@version` 等信息的过滤。\n\n可以同时指定多个。\n\n可引入 `idoc-api` 自行定义。\n\n# 自定义 Filter \n\n可以参考当前项目的 `idoc-test` 模块。 \n\n整体配置如下:\n\n```xml\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003ecom.github.houbb\u003c/groupId\u003e\n            \u003cartifactId\u003eidoc-core\u003c/artifactId\u003e\n            \u003cversion\u003e0.3.0\u003c/version\u003e\n            \u003cconfiguration\u003e\n                \u003cisAllInOne\u003etrue\u003c/isAllInOne\u003e\n                \u003cgenerates\u003e\n                    \u003cgenerate\u003ecom.github.houbb.idoc.ftl.api.generator.MarkdownDocGenerator\u003c/generate\u003e\n                \u003c/generates\u003e\n                \u003cgenerateFilters\u003e\n                    \u003cgenerateFilter\u003ecom.github.houbb.idoc.test.filter.MyGenerateFilter\u003c/generateFilter\u003e\n                \u003c/generateFilters\u003e\n            \u003c/configuration\u003e\n            \u003cdependencies\u003e\n                \u003cdependency\u003e\n                    \u003cgroupId\u003ecom.github.houbb\u003c/groupId\u003e\n                    \u003cartifactId\u003eidoc-test\u003c/artifactId\u003e\n                    \u003cversion\u003e${project.version}\u003c/version\u003e\n                \u003c/dependency\u003e\n            \u003c/dependencies\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\n## 指定文档生成器\n\n指定使用 Markdown 文档生成器，可以同时指定多个。\n\n```xml\n\u003cgenerates\u003e\n    \u003cgenerate\u003ecom.github.houbb.idoc.ftl.api.generator.MarkdownDocGenerator\u003c/generate\u003e\n\u003c/generates\u003e\n```\n\n### 引入包\n\nMarkdownDocGenerator 在 `idoc-ftl` 模块中，需要引入对应的依赖。\n\n当然 `idoc-core` 默认依赖 `idoc-ftl`。\n\n## 指定文件生成类的过滤器\n\n如果不定义自己的类生成过滤器，则会生成所有的类信息。\n\n一般使用中我们只关心 service 方法，所以添加了类的过滤实现。\n\n实现如下：\n\n### 引入 idoc-api 包\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.houbb\u003c/groupId\u003e\n    \u003cartifactId\u003eidoc-api\u003c/artifactId\u003e\n    \u003cversion\u003e${project.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### 实现 IDocGenerateFilter\n\n```java\npackage com.github.houbb.idoc.test.filter;\n\nimport com.github.houbb.idoc.api.core.filter.IDocGenerateFilter;\nimport com.github.houbb.idoc.api.model.metadata.DocClass;\n\n/**\n * 自定义生成过滤器\n * @author binbin.hou\n * @since 0.0.1\n */\npublic class MyGenerateFilter implements IDocGenerateFilter {\n\n    @Override\n    public boolean include(DocClass docClass) {\n        if(\"QueryUserService\".equalsIgnoreCase(docClass.getName())) {\n            return true;\n        }\n        return false;\n    }\n\n}\n```\n\n### 插件中配置使用\n\n```xml\n\u003cgenerateFilters\u003e\n    \u003cgenerateFilter\u003ecom.github.houbb.idoc.test.filter.MyGenerateFilter\u003c/generateFilter\u003e\n\u003c/generateFilters\u003e\n```\n\n注意，也需要将你定义这个过滤器的 jar 添加依赖，否则无法找到对应的类信息。\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.github.houbb\u003c/groupId\u003e\n        \u003cartifactId\u003eidoc-test\u003c/artifactId\u003e\n        \u003cversion\u003e${project.version}\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n\n# 类代码信息\n\n## User 信息\n\n```java\n/**\n * 用户信息\n * @author binbin.hou\n * @since 0.0.1\n */\npublic class User {\n\n    /**\n     * 名称\n     * @require 是\n     * @remark 中文名称，请认真填写\n     */\n    private String name;\n\n    /**\n     * 年龄\n     */\n    private int age;\n\n    /**\n     * 生日\n     */\n    private Date birthday;\n\n    /**\n     * 地址\n     */\n    private List\u003cAddress\u003e addressList;\n\n    /**\n     * 伴侣\n     */\n    private User mate;\n    \n    //...\n}\n```\n\n### i-doc 定义的标签\n\n`@require` 表示当前字段是否必填，作为方法入参时。\n\n`@remark` 表示当前字段的备注信息。\n\n## 方法类信息\n\n- QueryUserService.java\n\n```java\n/**\n * 查询用户服务类\n * @author binbin.hou\n * @since 0.0.1\n */\npublic interface QueryUserService {\n\n    /**\n     * 根据用户信息查询用户\n     * @param user 用户信息\n     * @return 结果\n     * @since 0.0.2,2019/02/12\n     */\n    public User queryUser(final User user);\n\n}\n```\n\n## 执行插件\n\n```\nmvn com.github.houbb:idoc-core:0.3.0:idoc\n```\n\n- 日志信息\n\n```\n[INFO] ------------------------------------ Start generate doc\n[INFO] 共计 【4】 个文件待处理，请耐心等待。进度如下：\n==================================================================================================== 100%\n[INFO] Generator doc with docGenerator: com.github.houbb.idoc.ftl.api.generator.MarkdownDocGenerator\n[INFO] Markdown 生成文档文件 all in one 路径: /Users/houbinbin/code/_github/idoc/idoc-test/src/main/resources/idoc-gen/idoc-test-全部文档.md\n[INFO] ------------------------------------ Finish generate doc\n```\n\n## 文档信息\n\n当前文件路径日志会打印，比如我自己测试的为：\n\n`/Users/houbinbin/code/_github/idoc/idoc-test/src/main/resources/idoc-gen/idoc-test-全部文档.md`\n\n## 文档生成效果\n\n参见文档:\n\n\u003e [idoc-test-全部文档.md](doc/blog/demo/idoc-test-全部文档.md)\n\n# 字段类型别名支持\n\n可以参考当前项目的 `idoc-test` 模块。\n\n## 为什么需要\n\n有时候页面显示类型，希望更加友好。\n\n所以系统内置了一些别名显示，也同时支持自定义别名。\n \n# 类型字段的别名\n\n## 系统内置\n\n系统当前版本提供了常见的别名。\n\n详情见 `com.github.houbb.idoc.core.util.JavaTypeAliasUtil`\n\n| 类型 | 别称 |\n|:---|:---|\n| java.lang.Float | 浮点型 |\n| java.lang.Double | 浮点型 |\n| java.util.Date | 日期 |\n| java.time.LocalDateTime | 日期时间 |\n| java.util.Currency | 货币 |\n| float | 浮点型 |\n| java.lang.Integer | 整型 |\n| long | 长整型 |\n| java.math.BigDecimal | 数字 |\n| java.lang.Character | 字符 |\n| java.lang.Long | 长整型 |\n| java.lang.Short | 短整型 |\n| java.util.Map | 映射 |\n| java.time.LocalTime | 时间 |\n| java.lang.Boolean | 布尔值 |\n| java.math.BigInteger | 数字 |\n| java.lang.String | 字符串 |\n| java.lang.Byte | 字节 |\n| double | 浮点型 |\n| byte | 字节 |\n| java.util.Collection | 集合 |\n| int | 整型 |\n| java.util.List | 列表 |\n| boolean | 布尔值 |\n| java.time.LocalDate | 日期 |\n| char | 字符 |\n| short | 短整型 |\n| void | 空 |\n| array | 数组 |\n \n## 自定义的方式\n\n可以通过 typeAlias 指定自定义的字段别称。\n\n```xml\n\u003cconfiguration\u003e\n    \u003cgenerateFilters\u003e\n        \u003cgenerateFilter\u003ecom.github.houbb.idoc.test.filter.MyGenerateFilter\u003c/generateFilter\u003e\n    \u003c/generateFilters\u003e\n    \u003cisAllInOne\u003etrue\u003c/isAllInOne\u003e\n    \u003ctypeAliases\u003e\n        \u003ctypeAlias\u003e\n            \u003ckey\u003ejava.lang.String\u003c/key\u003e\n            \u003cvalue\u003eString自定义说明\u003c/value\u003e\n        \u003c/typeAlias\u003e\n    \u003c/typeAliases\u003e\n\u003c/configuration\u003e\n```\n\n## 优先级\n\n用户自定义的字段别名优先级高于系统默认。\n\n后面定义的别名会直接覆盖前面的别名。\n\n# 测试代码演示\n\n## 对象定义\n\n```java\n/**\n * 别名测试\n * @author binbin.hou\n * @since 0.0.1\n */\npublic class TypeAliasSimpleBean {\n\n    /**\n     * 名称\n     */\n    private String name;\n\n    public String getName() {\n        return name;\n    }\n\n    public void setName(String name) {\n        this.name = name;\n    }\n}\n```\n\n## 测试日志\n\n运行测试日志如下：\n\n```\n{\"comment\":\"别名测试\",\"docAnnotationList\":[],\"docFieldList\":[{\"comment\":\"名称\",\"name\":\"name\",\"type\":\"java.lang.String\",\"typeAlias\":\"String自定义说明\"}],\"docMethodList\":[{\"docMethodParameterList\":[],\"docMethodReturn\":{\"fullName\":\"java.lang.String\",\"name\":\"String\",\"packageName\":\"java.lang\"},\"docTagList\":[],\"exceptionList\":[],\"modifiers\":[\"public\"],\"name\":\"getName\",\"seeList\":[],\"signature\":\"getName()\"},{\"docMethodParameterList\":[{\"docAnnotationList\":[],\"name\":\"name\",\"type\":\"java.lang.String\",\"typeAlias\":\"String自定义说明\"}],\"docMethodReturn\":{},\"docTagList\":[],\"exceptionList\":[],\"modifiers\":[\"public\"],\"name\":\"setName\",\"seeList\":[],\"signature\":\"setName(name)\"}],\"docTagList\":[{\"lineNum\":5,\"name\":\"author\",\"parameters\":[\"binbin.hou\"],\"value\":\"binbin.hou\"},{\"lineNum\":6,\"name\":\"since\",\"parameters\":[\"0.0.1\"],\"value\":\"0.0.1\"}],\"fullName\":\"com.github.houbb.idoc.test.model.TypeAliasSimpleBean\",\"modifiers\":[\"public\"],\"name\":\"TypeAliasSimpleBean\",\"packageName\":\"com.github.houbb.idoc.test.model\"}\n```\n\n其中 typeAlias 就是字段类型的别名，我们可以用来更加友好的显示字段信息。\n\n# 其他的思考\n\n## 自定义方式的便利性\n\n自定义的方式采用基于 xml 的方式是比较方便。\n\n但是数量比较多的时候就没有那么方便，本来考虑添加对应的配置属性接口，权衡下还是使用了 xml 配置的方式。\n\n## 是否使用 comment 信息？\n\n如果一个字段，没有指定别名，是否使用 comment 信息做替代？\n\n建议使用，当前版本不做处理。\n\n- 为什么使用\n\n比起冗长的类信息，大部分人更乐于看到解释。\n\n如果是针对同构的系统(都是 java 语言)，则可以理解。\n\n如果是针对异构的系统(比如前台是 php)，则不易于理解。\n\n- 为什么不处理\n\n大部分的接口都是常见字段, 性价比不高。\n\n可能存在字段没有些 comment 的情况，会导致判断的复杂性。\n\n## 如果用户不想使用别名\n\n直接修改模板即可，使用原来的字段 `type` 属性即可。\n\n# 开源地址\n\n\u003e [https://github.com/houbb/idoc](https://github.com/houbb/idoc)\n\n当然，这个项目还有很长的路要走。\n\n如果喜欢，欢迎 fork star~\n\n# ROAD-MAP\n\n- [x] 指定输出路径\n\n- [ ] 支持自定义类排序，方法排序\n\n- [ ] 完善 field 列表信息\n\n- [ ] 支持 version author 等基本信息\n\n- [ ] 列表添加序号信息\n\n- [ ] 更多的文档格式\n\nmd\nhtml\npdf\nexcel\nword\n\n- [ ] 版本管理\n\n不同版本之间的对比\n\n- [x] 添加索引文件\n\n当为多个文件时\n\n- [x] 优化参数显示\n\n如果没有，则直接显示无\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoubb%2Fidoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhoubb%2Fidoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoubb%2Fidoc/lists"}