 |
rxswiftAug 11, 2022
1
有什么好办法吗
|
 |
pigmenAug 11, 2022
2
那为啥不用 swagger 呢？
|
 |
BeautifulSoapAug 11, 2022 via Android
3
还有人手写 swagger 的？。。。。。
就算你项目没开始写代码，先随便用个框架简单定义好空的 controller 还有 DTO ，直接生成 swagger 不就好了，不至于手写 swagger |
 |
4
@BeautifulSoap 之前一家是 swagger 很方便 这家不让用 swagger 必须手写 api 文档
|
 |
issakchillAug 11, 2022
5
搞个 yapi 无侵入的输出吧 手写也太累了吧
|
 |
freebird1994Aug 11, 2022 via Android
6
yapi 手填文档，apipost 和 postman 一样做接口自测，可以根据返回的数据结构生成文档（自己写注释），应该都比你现在效率高些而且好维护些
|
 |
AV1Aug 11, 2022 via Android
7
我觉得你对接的前端同事面对这样的文档，也会跟你一样难受。
我觉得你们可以学一下 typescript 的 interface 语法，用来当作对象字段描述语言，表达那些复杂的对象会方便一些，前段同事也能方便对接字段。 |
 |
8
postman 肯定是要走一遍的
我前端 接过 postman 没走一遍的 后端 api 每次都有 api 问题, 一问后端, 自己都没测试过. |
 |
VegetableAug 11, 2022
9
...写空 Controller 先生成文档不行吗
|
 |
winglight2016Aug 11, 2022
10
swagger 也支持自定义模板的，为啥不自己定制一下？实在不行自己解析一下 api json ，用模板生成一下
|
 |
11
apifox 自动生成 api 在线共享,爽的一比,打灰机
|
 |
v2ebAug 11, 2022 via Android
12
有根据 javadoc 生成文档的。smart-doc
|
 |
hsuyeungAug 11, 2022
13
knife4j 的文档导出功能，导出成 word 应该可以吧，我试了下，感觉格式还行
|
 |
dingyaguang117Aug 11, 2022
15
stoplight 了解一下
|
 |
LeooooooAug 11, 2022
16
花一天时间写个自动化工具，只需要手动补充文档释义。节省未来一大半精力，还有成就感。
|
 |
BearCookieAug 11, 2022
17
有啥现成好法子不
|
 |
dumbassAug 11, 2022 via iPhone
18
对接的前端大概也很难受，现在做的项目接口文档用的 word ，看着很难受，而且没有用等宽字体 l 和 I 都分不清😅，只好全局替换成等宽字体。
|
 |
isekiAug 12, 2022 via Android
19
要么写代码生成文档，要么写文档生成代码，既写代码又写文档这的确烦人，时间一久就容易代码文档对不上
|
 |
kkeepAug 12, 2022 via Android
20
我有解决办法，半夜起来加班，在前端开始做之前，接口就 ready
|
 |
MarioLuoAug 12, 2022 via Android
21
如果是用的 spring ，可以用这个 Idea 插件，从标准 Java doc 生成代码: https://github.com/jetplugins/yapix
|
 |
NPC666Aug 12, 2022 via Android
22
我们是手写 swagger ，一个 yml 文件上万行，复制粘贴的时候 IDE 都要卡一会儿😅
|
 |
xiao109Aug 12, 2022
23
swagger 连他亲爹都放弃了吧
|
 |
bitminAug 12, 2022 via Android
24
yapi github 的 readme 上推荐了一些 idea 插件，我最近在用 easy-yapi 这个插件。因为写着 easy 就点开看了。代码无侵入，通过 Javadoc API 生成文档。可以导出到 yapi postman 等。还提供了一些增强的配置，可以配置回调。
我打算提交代码到 gitlab 的时候自动执行工具生成导出到 yapi ，有没有这样的工具？ |
 |
94Aug 12, 2022
25
考虑一下 yapi 这种可以生成接口文档的东西？
|
 |
leeUpAug 12, 2022
26
可以自己本地用 swagger 生成，然后用 postman 导入，这样就可以了
|
 |
27
试试我写的 idea 插件: Doc View
|
 |
littleMouseAug 12, 2022
28
为啥我们是前端写 api 文档啊，好痛苦┭┮﹏┭┮
|
 |
C603H6r18Q1mSP9NAug 12, 2022
29
写完自己不测试一遍？
没有测试测接口？ |
 |
xuanbgAug 12, 2022
30
手写 API 文档就是在模版上做几道填空题嘛，好写的很！而且我都是先把文档写好再开始写代码的。
|
 |
cccssssAug 12, 2022
32
曾经我也很痛苦，然后我花了大半天用 javaparser-core 写了一个获取 java doc 的小脚本就搞定了，一共 400 行代码
|
 |
xuboyingAug 12, 2022
33
手工写的文档用户一般是不信任的。。。。
|
 |
35
对于不让使用 Swagger 、不让使用 Lombok 、不让使用 IDEA ，不让使用方便程序开发，而又讲不出有力禁止理由的规定，都是耍流氓。程序的本质是什么？就是解放劳动力，提高生产力，把手动工作，编排成机器自动的工作。一切程序可以自动替代的，都应该由程序来做！
|
 |
alen0206Aug 12, 2022
36
如果是用的 Yapi 可以用 YapiUpload 插件 接口定义写完就能上传
|
|
37
@bitmin smart-doc maven 插件 自己扩展下上传到 yapi 可以实现，但是有个问题，多分支开发怎么弄，yapi 本身的文档管理功能没有多分支，多版本的概念
|
 |
CodeCodeStudyAug 12, 2022
38
做完不测试吗，测试的话 postman 的流程也要走一遍吧
|
 |
NoKeyAug 12, 2022
39
你完全可以搞个 idea ，然后在里面写 controller 及各参数，要么用 swagger ，要么 idea 加一些插件，能生成 request body 的 json 结构，写文档也快。手写 api ，也不是完全不写代码，比如要 uml 图，你真的手写去画么？ idea 先写一些伪代码，自动生成了复制啊
|
 |
RainCatsAug 12, 2022
40
用模板技术去生成，提前写好模板就好了
|
 |
shalkAug 12, 2022
41
自己想办法生成一下，再稍微改改
|
 |
18601294989Aug 12, 2022
42
swagger 导出到 postman 就好了吧
|
 |
lpbname777Aug 12, 2022
43
@zhuangzhuang1988 雾草！后端接口盲写 同感
|
 |
aicfeAug 12, 2022
44
我用 yapi + idea 上安装 easyYapi 插件 一键导出 还能给前端 mock
|
|
zhuangzhuang1988Aug 12, 2022 via Android
45
@lpbname777 遇到太多了，前端当测试，最基础的数据都过不了
|
 |
edward1987Aug 12, 2022
46
无论输出是什么,都要自动化
|
 |
xuxuzhaozhaoAug 12, 2022
47
了解一下 ApiPost ，爽得呀丕
|
 |
potatowishAug 12, 2022 via iPhone
48
不让用 swagger 估计是侵入代码层了，考虑下无侵入的方式，比如说 smart-doc ，或者是基于单元测试的，sping rest doc 离线文档
|
 |
nothingistrueAug 12, 2022
49
目测你在移动、联通系统集成或者类似这样的企业里面做外包，或者是对日外包。死板的 CMMI 规范，一行代码一百页文档，自己不想干就让外包的人干。
|
 |
lllllliiiiAug 12, 2022
50
可以试试 easy yapi 导出 md 文档
|
 |
StarkWhiteAug 12, 2022
51
fb 的 graphql 了解下，文档不用写了
https://v2ex.com/t/589138?p=2#reply137 |
|
52
@nothingistrue 并不是 是个 to c 互联网企业 反而之前是在做电信项目的公司用的 swagger
|
 |
hetalAug 12, 2022
53
protobuf 不香么，配合 doc 工具自动生成 api 文档，再加一个 restful 网关就行了
|
 |
tiedanAug 12, 2022
54
我的关注点是一个需求十几个新 api 。。。 这么恐怖吗
|
 |
gzlixiaochao555Aug 12, 2022
55
可以试试 Eolink ，通过 swagger.json 直接生成接口文档，支持在线测试
|
 |
watzdsAug 12, 2022
56
IDEA 装 EasyApi 插件，写完 Controller 能直接同步到 yapi, postman 等地方，很方便啊
|
 |
pengtdydAug 12, 2022
57
S 13 的技术管理，就是有这些奇葩的事情。
|
 |
ClarkAbeAug 13, 2022 via Android
58
我司也是我这边五个大模块将近四百个接口前几天主管说用手写文档还要一个月内开发完....我直接就怼回去了
|
|
xuanbgAug 15, 2022
60
@still97 对象嵌套不是很正常的嘛，问题是你要怎么去描述。我就是把所有对象都用表格描述，表格里面有一列叫类型，那么某个字段该是什么类型就加个跳转指向那个类型的表格就好了呀。
一般这个没人看的，因为我提供了示例数据，包括入参和返回数据。前端看到返回数据的示例，就知道接口返回是什么。只要照抄我提供的参数，就能返回期望的数据。 |
 |
ricebnaOct 14, 2023
62
对于接口文档的编写， 我觉得用任何工具都会有效率耗损。包括 yapi ，postman ，还有注释类的 swagger 。
接口文档特别是内部用的并且是前端用的，95%的情况就是一个简单的输出与输入，主要工作是描述清楚字段结构，主要目的是与前端达成沟通以及存档的作用，并不需要多么标准化。 而各种工具，无论是界面类的还是注释自动转换类的， 都需要遵照特定规范，按要求去填写。 点击一个输入框或是写上特定注释标记都需要额外的时间与心智消耗，这些精准规范其实没必要, 并且他们(特别是国产工具)都经不起时间的变化, 另外维护更新工作也是一个反人性大家都不想做的事情。 所以我在想在写文档的效率方面， 直接用最简单的文本是最方便的，直接在代码编辑器写注释文本，不需要遵照特定注释规范, 特别是输出参数比较多, 层级也多, 直接用所见即所得的 json 文本本身做为描述是最简单的。无需担心格式出错, 维护更新也在相同的地方, 没有割裂感. 并且他们的经得起时间的沉淀 (越简单的东西, 他们的存在度和稳定性就越高, 日后你想要转换成任何文档形式都可以. 这也是我对于笔记应用的一个观念转变: 从印象笔记到后来直接用 vscode 写 md, 到现在 md 只不过是一个文件后缀而实际很少用它的语法了, 而同步功能直接用谷歌云盘同步目录, git 不定期备份. 大道至简) 然后把我们写得不那么标准的简化注释用 ChatGPT 转换成勉强标准的结构化文档，它就适合做这类不精准的东西，还有纠错能力。 我试过了，它转换成的 postman 导入文件居然是对的，我还担心这种事情它一般会出错，不过凡涉及代码的东西最好不用，有时出错给它排错的时间不值。 [Imgur](  ) |
10
Select Language