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

各位的开发需要编写的文档是怎么弄出来的?

  •  
  •   tctc4869 · 2021-07-22 09:27:18 +08:00 · 3145 次点击
    这是一个创建于 980 天前的主题,其中的信息可能已经有所发展或是发生改变。

    开发过程中,免不了要需要弄出文档来。目前我所知的开发文档分为 Api 接口文档,数据模型文档,测试文档。

    这类文档各位是怎么弄出来的?

    是在开发写代码之前弄?,那就是自己在 word 文件上,或在线文档管理网站里面,打字手写出来的。这样的话,感觉挺耗费时间的,不累吗,一开始能想出所有的内容吗?

    是在开发过程中弄?那是通过自定义文档生成吗。在类和接口方法上,标注注释类似 java 的注解。然后通过自己写的或别人写的文档生成工具扫描这类内容,生成 html 或者 json 或者 word 。自己在手写打字补充一些内容。

    我个人是倾向于读取开发代码的内容,并生成文档的方式,来弄出文档的。

    18 条回复    2021-09-29 00:04:59 +08:00
    3dwelcome
        1
    3dwelcome  
       2021-07-22 09:40:48 +08:00
    "读取开发代码的内容"

    这 JavaDoc 方法对于文档少的可以,文档多了以后,会有太多注释信息,反而会让代码变得比较难阅读,不是很顺畅。

    个人不太喜欢 Java 那种 2/3 注释,1/3 代码的那种占比模式。一个文件里,有 1/5 注释,4/5 代码会好很多。

    真要写大量接口,比如开发 SDK 文档。我会另外分一个 meta.json,对源代码函数和功能做额外说明,最后发布文档的时候,整合到一起。
    www5070504
        2
    www5070504  
       2021-07-22 09:48:28 +08:00
    "读取开发代码的内容" 这对团队的执行力和规范性的要求很高
    www5070504
        3
    www5070504  
       2021-07-22 09:48:36 +08:00
    不过确实省事很多
    ganning
        4
    ganning  
       2021-07-22 09:50:10 +08:00
    接口开发,自验完成,再用 Markdown 写一写。

    ps:虽然提供了 API 文档,但前端和移动端从来不看,有问题就来我工位上问。。。你要是不写,就直接在群里找你要。无语
    debuggerx
        5
    debuggerx  
       2021-07-22 09:56:15 +08:00
    我还是站注释生成代码的思路,因为定义 /编写文档的位置离代码本身越远,修改同步的成本越高,准确度可信度越低,除非能有一套完整可靠的 workflow 能强制修改接口代码后一定要更新文档定义。那种单独维护一份定义文件的,或者在独立平台上维护接口文档的,想要维护好对团队的执行力和规范要求更高,写在注释的定义可以方便地直接在 code review 阶段检查。
    而且现在的 IDE 都是有源码大纲视图的,并不用担心加入过长注释导致源码难度的问题。而且这些注释只用写在 controller 层,逻辑实现层又不需要,影响也不是很大的。
    chendy
        6
    chendy  
       2021-07-22 10:13:45 +08:00
    对 swagger 这种东西迷之反感,虽然一定程度上保证代码文档一致,但是,别扭
    感觉还是应该有一个平台用来单独管理文档,然后可以从上面测试接口,检查接口健康,记录接口变更,生成接口基本代码,巴拉巴拉
    tctc4869
        7
    tctc4869  
    OP
       2021-07-22 11:00:47 +08:00
    @chendy 读取开发代码内容生成文档,不只是包括读取注解。有的工具可以直接读取接口方法上的注释的
    chendy
        8
    chendy  
       2021-07-22 11:20:45 +08:00
    @tctc4869 #7 emm…我自己写过这类东西,甚至不用注解,全靠注释就可以出 openapi 格式的东西然后塞进 swagger
    来来回回做了两年,最后觉得真正需要的是接口管理,而不只是接口文档生成
    wanguorui123
        9
    wanguorui123  
       2021-07-22 12:25:40 +08:00
    swagger 注解,代码注解
    Administrat0r
        10
    Administrat0r  
       2021-07-22 12:34:45 +08:00
    graphql 一把梭
    tctc4869
        11
    tctc4869  
    OP
       2021-07-22 13:54:27 +08:00
    @ganning 素质问题把
    Gunn27
        12
    Gunn27  
       2021-07-22 18:27:57 +08:00
    我们开发过程中前后端是同时进行的,不可能前端等后端写完接口再开始工作,所以你说的根据代码注释来生成文档是不现实的。
    文档驱动开发一定是高效团队的所推崇的,在开发工作开始前,必须要先产出 API 文档并且前后端评审通过,之后开发人员只需要根据文档来进行开发就可以了,谁也不需要等谁。
    我们的 API 文档和 DB 文档都是在 ApiCat 上设计完成的,编写和维护都很方便。
    xuanbg
        13
    xuanbg  
       2021-07-22 21:24:54 +08:00
    1 、功能结构图肯定要画的,就是脑图,很简单。但不管多小的系统,必画。
    2 、复杂流程肯定要画流程图,画完要修改至少 3 个版本。
    3 、数据库建表脚本。

    接口文档对外的话肯定要写的,对内就不写了。因为所有接口都能导出 curl 的脚本,前端拿着这个比看文档简单多了。
    tctc4869
        14
    tctc4869  
    OP
       2021-07-23 09:56:18 +08:00
    @Gunn27 你这个是面向项目开发文档的团队开发,以项目开发文档为开发理念指导。所以在这个环境下,事先写项目开发文档就很重要了。

    但是并不是所有的项目开发的流程,都会采用你所说的方式。
    tctc4869
        15
    tctc4869  
    OP
       2021-07-23 10:02:51 +08:00
    @xuanbg 接口都能导出 cur ?通过对接口代码扫描做的?
    SmiteChow
        16
    SmiteChow  
       2021-07-23 14:09:03 +08:00
    API 接口可以用代码里注释自动生成,但教程和架构说明就真只能手写了,专业的开发者文档写得也很漂亮的。
    godall
        17
    godall  
       2021-07-29 14:13:50 +08:00
    @SmiteChow 你看到谁的写的漂亮的?感觉大部分都是一枪头,第一稿漂亮的,接着就跟不上了。
    MarioLuo
        18
    MarioLuo  
       2021-09-29 00:04:59 +08:00 via Android
    1. API 文档: 代码定义接口层,自动生成上传到 YApi, 配合 mock,满足前后端同时开发
    2. 数据库文档: 简单直接维护 sql 逆向生成,或者一开始就用 pmd 类似工具维护表结构
    3.测试文档,不知道,毕竟是开发,逃

    API 文档生成,可以用这个插件: github.com/jetplugins/yapix
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   3103 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 29ms · UTC 12:55 · PVG 20:55 · LAX 05:55 · JFK 08:55
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.