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

[tctc4869]

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

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

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

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

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

[3dwelcome]

"读取开发代码的内容"

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

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

真要写大量接口，比如开发 SDK 文档。我会另外分一个 meta.json，对源代码函数和功能做额外说明，最后发布文档的时候，整合到一起。

[www5070504]

"读取开发代码的内容" 这对团队的执行力和规范性的要求很高

[www5070504]

不过确实省事很多

[ganning]

接口开发，自验完成，再用 Markdown 写一写。

ps：虽然提供了 API 文档，但前端和移动端从来不看，有问题就来我工位上问。。。你要是不写，就直接在群里找你要。无语

[debuggerx]

我还是站注释生成代码的思路，因为定义 /编写文档的位置离代码本身越远，修改同步的成本越高，准确度可信度越低，除非能有一套完整可靠的 workflow 能强制修改接口代码后一定要更新文档定义。那种单独维护一份定义文件的，或者在独立平台上维护接口文档的，想要维护好对团队的执行力和规范要求更高，写在注释的定义可以方便地直接在 code review 阶段检查。
而且现在的 IDE 都是有源码大纲视图的，并不用担心加入过长注释导致源码难度的问题。而且这些注释只用写在 controller 层，逻辑实现层又不需要，影响也不是很大的。

[chendy]

对 swagger 这种东西迷之反感，虽然一定程度上保证代码文档一致，但是，别扭
感觉还是应该有一个平台用来单独管理文档，然后可以从上面测试接口，检查接口健康，记录接口变更，生成接口基本代码，巴拉巴拉

[tctc4869]

@chendy 读取开发代码内容生成文档，不只是包括读取注解。有的工具可以直接读取接口方法上的注释的

[chendy]

@tctc4869 #7 emm…我自己写过这类东西，甚至不用注解，全靠注释就可以出 openapi 格式的东西然后塞进 swagger
来来回回做了两年，最后觉得真正需要的是接口管理，而不只是接口文档生成

[wanguorui123]

swagger 注解，代码注解

[Administrat0r]

graphql 一把梭

[tctc4869]

@ganning 素质问题把

[Gunn27]

我们开发过程中前后端是同时进行的，不可能前端等后端写完接口再开始工作，所以你说的根据代码注释来生成文档是不现实的。
文档驱动开发一定是高效团队的所推崇的，在开发工作开始前，必须要先产出 API 文档并且前后端评审通过，之后开发人员只需要根据文档来进行开发就可以了，谁也不需要等谁。
我们的 API 文档和 DB 文档都是在 ApiCat 上设计完成的，编写和维护都很方便。

[xuanbg]

1 、功能结构图肯定要画的，就是脑图，很简单。但不管多小的系统，必画。
2 、复杂流程肯定要画流程图，画完要修改至少 3 个版本。
3 、数据库建表脚本。

接口文档对外的话肯定要写的，对内就不写了。因为所有接口都能导出 curl 的脚本，前端拿着这个比看文档简单多了。

[tctc4869]

@Gunn27 你这个是面向项目开发文档的团队开发，以项目开发文档为开发理念指导。所以在这个环境下，事先写项目开发文档就很重要了。

但是并不是所有的项目开发的流程，都会采用你所说的方式。

[tctc4869]

@xuanbg 接口都能导出 cur ？通过对接口代码扫描做的？

[SmiteChow]

API 接口可以用代码里注释自动生成，但教程和架构说明就真只能手写了，专业的开发者文档写得也很漂亮的。

[godall]

@SmiteChow 你看到谁的写的漂亮的？感觉大部分都是一枪头，第一稿漂亮的，接着就跟不上了。

[MarioLuo]

1. API 文档: 代码定义接口层，自动生成上传到 YApi, 配合 mock，满足前后端同时开发
2. 数据库文档: 简单直接维护 sql 逆向生成，或者一开始就用 pmd 类似工具维护表结构
3.测试文档，不知道，毕竟是开发，逃

API 文档生成，可以用这个插件: github.com/jetplugins/yapix