V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
smartdoc647
V2EX  ›  程序员

推荐一个 Java 零注解零侵入 API 文档生成工具

  •  
  •   smartdoc647 · 2019-12-05 22:24:20 +08:00 · 5188 次点击
    这是一个创建于 1574 天前的主题,其中的信息可能已经有所发展或是发生改变。

    在过去,java web 开发者生产文档通常需要引入 swagger,然后写一堆注解侵入到业务代码中,这让很多开发者很讨厌。2018 年一款基于源码分析的零注解零侵入文档生成工具 smart-doc 正式在开源中国开源。经过一年多的时间 smart-doc 已经被中国上百家中小企业集成到公司的项目生成 api 接口文档。甚至有像科大讯飞、一加这样的知名企业用户。smart-doc 不侵入,并且几乎没有使用学习成本。在一年多的版本迭代中也完善了使用文档。目前主要支持 SpringBoot 技术栈开发的文档生成。想使用的 java 开发这可以查看 smart-doc 项目: github: https://github.com/shalousun/smart-doc.git gitee: https://gitee.com/sunyurepository/smart-doc.git

    12 条回复    2019-12-06 15:14:05 +08:00
    liumyao
        1
    liumyao  
       2019-12-05 23:06:01 +08:00 via Android
    周末试试 感觉还不错 很烦侵入式
    ke1e
        2
    ke1e  
       2019-12-05 23:11:25 +08:00 via Android
    感觉 swagger 注释的同时也是给自己看,可以接受
    smartdoc647
        3
    smartdoc647  
    OP
       2019-12-05 23:30:33 +08:00
    smart-doc 是强制要求写注释的,上百家企业选择不是自己吹的,没有好的点就成烂尾项目了
    chendy
        4
    chendy  
       2019-12-05 23:31:01 +08:00
    分享一下自己的半成品: https://github.com/chendy560/c2d
    cedoo22
        5
    cedoo22  
       2019-12-05 23:38:55 +08:00
    swagger 虽然入侵,但更强大。java doc 不方便直接生成易读性的文档生成,smart-doc 利用约定好的注释格式,生成文档,很强。我更大的需求是可以自动生成 html 静态资源,或自动直接在公司环境生成 web 版本,甚至自动在 web 端进行 REST 接口的简单测试。
    smartdoc647
        6
    smartdoc647  
    OP
       2019-12-05 23:47:12 +08:00
    smart-doc 支持生成静态 html、markdown、adoc 甚至是 postman 上测试的接口 json 文件,生成的 html 页面干净整理开用和 Spring 官方文档一样的模板样式,markdown 我们有很多用户稍微修改下就能转成 pdf 作为和外部公司的对接文档。postman 的 json 文件可以一键导入。码云上的 wiki 都有详细介绍。
    zgqq
        7
    zgqq  
       2019-12-05 23:58:44 +08:00
    之前是写一个类似的
    zhenjiachen
        8
    zhenjiachen  
       2019-12-06 09:13:44 +08:00
    看了一下是使用测试用例来生成的文档,但是 Spring 不是有一个 Spring Rest Doc 吗,可以直接和 mockMvc 的测试代码结合,更方便
    smartdoc647
        9
    smartdoc647  
    OP
       2019-12-06 09:49:50 +08:00
    注意看文档,一个单元测试仅仅用于启动 smart-doc 扫描代码,smart-doc 和 swagger、Spring Rest Doc 都不是一个原理,smart-doc 完全基于定义好的接口源码和注释分析生成文档。我一直的原则是,如果重复造轮子又不能比现有工具好没有意义。
    vincentguc
        10
    vincentguc  
       2019-12-06 11:40:58 +08:00
    非 springmvc 项目支持吗
    cweijan
        11
    cweijan  
       2019-12-06 13:11:34 +08:00
    vocabularies
        12
    vocabularies  
       2019-12-06 15:14:05 +08:00
    好东西 想在我米用了 刚和组长说了嘿嘿
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   3937 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 25ms · UTC 10:24 · PVG 18:24 · LAX 03:24 · JFK 06:24
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.