优于 swagger 的 java markdown 文档自动生成框架-01-入门使用

RdouTyping 发布于2019-08-16 15:53 / 1190人阅读

摘要：很多项目不写文档，即使写文档，对于开发人员来说也是非常痛苦的。无法保证及时更新。是基于注解的文档生成工具。让文档的阅读者享受到等同于手写文档的体验。将信息的获取和生成区分开。基于原生的注释，尽可能的生成简介的文档。

设计初衷 节约时间

Java 文档一直是一个大问题。

很多项目不写文档，即使写文档，对于开发人员来说也是非常痛苦的。

不写文档的缺点自不用多少，手动写文档的缺点也显而易见：

非常浪费时间，而且会出错。

无法保证及时更新。代码已经变了，但是文档还要同步修改。需要强制人来维护这一种一致性。这很难。

为什么不是 swagger-ui

java 的文档有几类：

jdk 自带的 doc 生成。这个以前实践给别人用过，别人用 C#，看到 java 的默认文档感觉很痛苦。

就算是我们 java 开发者，也很讨厌看 jdk 的文档。看着不美观，也很累。

swagger-ui 是基于 java 注解的文档生成工具。相对而言比较优雅，也非常强大。

但是缺点也是有的。开发人员要写 jdk 原来的注释+注解。注解太多，导致写起来也很痛苦，大部分开发者后来还是选择了放弃。

那么问题来了？我们怎么办才能尽可能的让开发人员，和文档阅读人员都乐于接受呢？

jdk 自带的 doc 就是基于 maven 插件的，本项目也是。

区别如下：

尽可能的保证和 Java 原生注释一致，让开发者很容易就可以使用。

尽可能的信息全面，但是文档简洁。让文档的阅读者享受到等同于手写文档的体验。

将信息的获取和生成区分开。方便用户自己定义自己的输出方式。

IDOC i-doc 项目简介

为 java 项目生成项目文档。

基于原生的 java 注释，尽可能的生成简介的文档。用户可以自定义自己的模板，生成自己需要的文档。

特性

基于 maven 项目生成包含大部分信息的元数据

默认支持 markdown 简化文档的生成，支持自定义模板

支持用户自定义文档生成器

支持用户自定生成文档的类过滤器

新特性

添加字段类型别名，支持用户自定义

快速入门 需要

jdk1.8+

maven 3.x+

maven 引入

使用 maven 引入当前 idoc 插件。


    
        
            com.github.houbb
            idoc-core
            0.1.0

测试对象的创建

为了演示文档，我们创建了一个 Address 对象。

package com.github.houbb.idoc.test.model;

/**
 * 地址
 * @author binbin.hou
 * @since 0.0.1
 */
public class Address {

    /**
     * 城市
     */
    private String country;

    /**
     * 街道
     */
    private String street;

    public String getCountry() {
        return country;
    }

    public void setCountry(String country) {
        this.country = country;
    }

    public String getStreet() {
        return street;
    }

    public void setStreet(String street) {
        this.street = street;
    }
}

执行插件

mvn com.github.houbb:idoc-core:0.0.2:idoc

命令行日志信息

[INFO] ------------------------------------ Start generate doc
[INFO] 共计 【1】 个文件待处理，请耐心等待。进度如下：
==================================================================================================== 100%
[INFO] Generator doc with docGenerator: com.github.houbb.idoc.core.api.generator.ConsoleDocGenerator
[INFO] ------------------------------------ 文档信息如下：

[类名] com.github.houbb.idoc.test.model.Address
[类信息] {"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"}

[INFO] ------------------------------------ Finish generate doc

Markdown 的生成

参考 03-自定义生成文件过滤器

效果参见 idoc-test-全部文档.md

进一步学习

00-项目概览

01-设计初衷

02-插件的参数配置

03-自定义生成文件过滤器

04-字段类型别名支持

开源地址

idoc

GPU云服务器云服务器 java框架入门使用java帮助文档 java01++ java01算法

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/73761.html

【效率专精系列】善用API统一描述语言提升RestAPI开发效率

摘要：其标准为前身是，提供强大的在线编辑功能，包括语法高亮错误提示自动完成实时预览，并且支持用户以格式撰写导入导出转换文档。团队内部RestAPI开发采用设计驱动开发的模式，即使用API设计文档解耦前端和后端的开发过程，双方只在联调与测试时耦合。在实际开发和与前端合作的过程中，受限于众多因素的影响，开发效率还有进一步提高的空间。本文的目的是优化工具链支持，减少一部分重复和枯燥的劳动。现状...

tianyu 2019-08-16 10:42 评论0 收藏0
api 接口管理工具

摘要：接口管理工具大致分为线上工具和自建工具。安装其他工具上面讲的，不管是线上工具还是自建工具，都是接口集成工具，主要是为了提供数据功能。类似网易云笔记印象笔记的笔记管理工具。 api 接口管理工具现在，Web 应用的前后端分离事实上已经成为了大家都认可的一种开发方式，前后端分离之后，前端与后端都用接口（api）来沟通，这就需要我们做好 API 接口管理，所以，这次来聊聊 API 接口管理...

marser 2019-08-23 14:43 评论0 收藏0
api 接口管理工具

摘要：接口管理工具大致分为线上工具和自建工具。安装其他工具上面讲的，不管是线上工具还是自建工具，都是接口集成工具，主要是为了提供数据功能。类似网易云笔记印象笔记的笔记管理工具。 api 接口管理工具现在，Web 应用的前后端分离事实上已经成为了大家都认可的一种开发方式，前后端分离之后，前端与后端都用接口（api）来沟通，这就需要我们做好 API 接口管理，所以，这次来聊聊 API 接口管理...

wuyumin 2019-08-16 14:27 评论0 收藏0
Wizard 开源文档管理系统1.0发布啦

摘要：总结如果你在为公司寻找一款开源免费的开发文档文档管理工具，不妨考虑一下项目，一定不会让你失望的。 Wizard 是一款开源文档管理系统，项目地址为 https://github.com/mylxsw/wizard。这个项目是我在2017年就开始开发的，起初只是想做一款能够在公司内部把Swagger文档管理起来的工具，但在这近两年的时间里，一直断断续续的为其添加各种功能，现在终于下决...

cod7ce 2019-07-01 12:44 评论0 收藏0
微服务横行的今天, 你的文档跟上节奏了么?

摘要：纳尼隔壁少林派表示自家金刚技压群雄在座各位都是。。。纳尼你觉得写太繁琐了你不喜欢我们还有或者等等一大堆工具呢。纳尼没有你还是觉得无法接受好吧那么笔者推荐类似这类更友好的工具你可以导入导出其他格式也可以使用其来撰写。说起微服务, 想必现在的技术圈内人士个个都能谈笑风云, 娓娓道来。的确, 技术变革日新月异, 各种工具框架雨后春笋般涌现, 现在我们可以轻巧便捷地根据自己的业务需求, 构建...

liaoyg8023 2019-08-14 16:55 评论0 收藏0