这是一个创建于 1251 天前的主题，其中的信息可能已经有所发展或是发生改变。
开发过程中，免不了要需要弄出文档来。目前我所知的开发文档分为 Api 接口文档，数据模型文档，测试文档。
这类文档各位是怎么弄出来的？
是在开发写代码之前弄？，那就是自己在 word 文件上，或在线文档管理网站里面，打字手写出来的。这样的话，感觉挺耗费时间的，不累吗，一开始能想出所有的内容吗？
是在开发过程中弄？那是通过自定义文档生成吗。在类和接口方法上，标注注释类似 java 的注解。然后通过自己写的或别人写的文档生成工具扫描这类内容，生成 html 或者 json 或者 word 。自己在手写打字补充一些内容。
我个人是倾向于读取开发代码的内容，并生成文档的方式，来弄出文档的。
 |
1
3dwelcome 2021-07-22 09:40:48 +08:00
"读取开发代码的内容"
这 JavaDoc 方法对于文档少的可以，文档多了以后，会有太多注释信息，反而会让代码变得比较难阅读，不是很顺畅。 个人不太喜欢 Java 那种 2/3 注释，1/3 代码的那种占比模式。一个文件里，有 1/5 注释，4/5 代码会好很多。 真要写大量接口，比如开发 SDK 文档。我会另外分一个 meta.json，对源代码函数和功能做额外说明，最后发布文档的时候，整合到一起。 |
 |
2
www5070504 2021-07-22 09:48:28 +08:00
"读取开发代码的内容" 这对团队的执行力和规范性的要求很高
|
|
3
www5070504 2021-07-22 09:48:36 +08:00
不过确实省事很多
|
 |
4
ganning 2021-07-22 09:50:10 +08:00
接口开发，自验完成，再用 Markdown 写一写。
ps：虽然提供了 API 文档，但前端和移动端从来不看，有问题就来我工位上问。。。你要是不写，就直接在群里找你要。无语 |
 |
5
debuggerx 2021-07-22 09:56:15 +08:00
我还是站注释生成代码的思路，因为定义 /编写文档的位置离代码本身越远，修改同步的成本越高，准确度可信度越低，除非能有一套完整可靠的 workflow 能强制修改接口代码后一定要更新文档定义。那种单独维护一份定义文件的，或者在独立平台上维护接口文档的，想要维护好对团队的执行力和规范要求更高，写在注释的定义可以方便地直接在 code review 阶段检查。
而且现在的 IDE 都是有源码大纲视图的，并不用担心加入过长注释导致源码难度的问题。而且这些注释只用写在 controller 层，逻辑实现层又不需要，影响也不是很大的。 |
 |
6
chendy 2021-07-22 10:13:45 +08:00
对 swagger 这种东西迷之反感，虽然一定程度上保证代码文档一致，但是，别扭
感觉还是应该有一个平台用来单独管理文档，然后可以从上面测试接口，检查接口健康，记录接口变更，生成接口基本代码，巴拉巴拉 |
|
8
chendy 2021-07-22 11:20:45 +08:00
@tctc4869 #7 emm…我自己写过这类东西，甚至不用注解，全靠注释就可以出 openapi 格式的东西然后塞进 swagger
来来回回做了两年，最后觉得真正需要的是接口管理，而不只是接口文档生成 |
 |
9
wanguorui123 2021-07-22 12:25:40 +08:00
swagger 注解，代码注解
|
 |
10
Administrat0r 2021-07-22 12:34:45 +08:00
graphql 一把梭
|
 |
12
Gunn27 2021-07-22 18:27:57 +08:00
我们开发过程中前后端是同时进行的，不可能前端等后端写完接口再开始工作，所以你说的根据代码注释来生成文档是不现实的。
文档驱动开发一定是高效团队的所推崇的，在开发工作开始前，必须要先产出 API 文档并且前后端评审通过，之后开发人员只需要根据文档来进行开发就可以了，谁也不需要等谁。 我们的 API 文档和 DB 文档都是在 ApiCat 上设计完成的，编写和维护都很方便。 |
 |
13
xuanbg 2021-07-22 21:24:54 +08:00
1 、功能结构图肯定要画的，就是脑图，很简单。但不管多小的系统，必画。
2 、复杂流程肯定要画流程图，画完要修改至少 3 个版本。 3 、数据库建表脚本。 接口文档对外的话肯定要写的，对内就不写了。因为所有接口都能导出 curl 的脚本，前端拿着这个比看文档简单多了。 |
 |
14
tctc4869 OP |
 |
16
SmiteChow 2021-07-23 14:09:03 +08:00
API 接口可以用代码里注释自动生成，但教程和架构说明就真只能手写了，专业的开发者文档写得也很漂亮的。
|
 |
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 |
Select Language