请问各位，公司内部的接口文档是怎么管理的？

请问

swagger-ui

swagger

接口

119 条回复 • 2018-11-29 20:23:15 +08:00

1 2

❮

❯

1

byuc

2017-09-12 19:53:08 +08:00

口口相传

2

qinxi

2017-09-12 19:53:50 +08:00

https://app.swaggerhub.com/ 这个?

3

yoa1q7y

2017-09-12 19:56:25 +08:00

口口相传+1

4

sudoz

2017-09-12 19:56:51 +08:00

confluence

5

Hypn0s

2017-09-12 19:59:42 +08:00

confluence + 1

6

gaayyy

2017-09-12 20:03:59 +08:00

靠猜

7

ZeoKarl

2017-09-12 20:04:10 +08:00

给你一个眼神,自己体会.🌚

8

fengxuejianshi

2017-09-12 20:18:15 +08:00 via iPhone

意念

9

aaxcc

2017-09-12 20:33:59 +08:00 via iPhone

当然是打印出来贴在公司大门上，每天程序猿进门背一个借口，背错的扣工资

10

cutlove

2017-09-12 20:43:57 +08:00

apizza

11

irgil

2017-09-12 20:45:40 +08:00

swagger，或者公司自研的。

12

orancho

2017-09-12 20:47:17 +08:00

protobuf / grpc 的 proto 文件

13

MrXiong

OP

2017-09-12 20:51:46 +08:00

@irgil swagger 有什么使用姿势

14

irgil

2017-09-12 21:28:12 +08:00

@MrXiong 主要是自动生成文档，自动生成代码

15

AndyJia

2017-09-12 22:23:45 +08:00 via Android

openapi

16

gemini

2017-09-12 22:29:09 +08:00

word 文档不挺好的么

17

iyaozhen

2017-09-12 22:30:12 +08:00 via Android

wiki，先定接口再开发

18

crossoverJie

2017-09-12 22:31:43 +08:00

之前 confluence 现在 swagger

19

hasbug

2017-09-12 22:43:24 +08:00

口口相传+1

20

m939594960

2017-09-12 22:44:40 +08:00

gitlab 的 wiki 功能

21

xiaolanglang

2017-09-12 23:13:16 +08:00

口口相传

22

fbzl

2017-09-13 00:15:48 +08:00 via iPhone

口口相传，心灵感应

23

lgh

2017-09-13 00:28:47 +08:00 via iPhone

@orancho #12 顺便问个相关的问题：pb 只能体现接口报文格式，你们是怎样管理 pb 和实际接口之间的关联关系这些信息的？

24

Jackeriss

2017-09-13 01:02:57 +08:00 via iPhone

这个全看悟性

25

junbguistar

2017-09-13 01:12:15 +08:00

接口多就自己搭 wiki 和 swagger 少就口口相传

26

49degree

2017-09-13 01:13:42 +08:00

RAP

27

fan123199

2017-09-13 01:14:59 +08:00

word 文档

28

Lucups

2017-09-13 01:19:33 +08:00

不同方式的文档都有各自的优劣和使用场景，我主要考虑沟通成本，哪种方式沟通成本小用哪种。
目前在公司用 confluence 手写，一个接口一个页面，其他部门人来要时直接丢链接。

PS：Swagger 默认的 UI 不是很好用。有同感的可以考虑这个项目 https://github.com/jensoleg/swagger-ui。

29

Lucups

2017-09-13 01:20:18 +08:00

我晕，加了空格还是把句号和链接合在一起了。。。重新补一下:

https://github.com/jensoleg/swagger-ui

30

Tyrion

2017-09-13 02:12:31 +08:00

confluence + 1

31

bombless

2017-09-13 02:24:17 +08:00 via Android

写代码注释里面的，靠自觉，很多人不写的。

听说大公司都是靠口口相传

32

feiyuanqiu

2017-09-13 03:18:32 +08:00 via Android

@Lucups 我最近刚好在改这个 ui。它有个问题是把接口参数放在 div 的属性里，导致没法选择及复制，而且参数名长一点的话就显示不全。另外我也不太喜欢它调用接口时单独弹出一个 modal 的方式

33

msg7086

2017-09-13 07:33:02 +08:00

早已失传……

34

motai

2017-09-13 08:13:53 +08:00 via iPhone

rap，word，内部的 wiki 系统

35

xtaxcy

2017-09-13 08:18:46 +08:00 via Android

小幺鸡

36

caijihui11

2017-09-13 08:37:49 +08:00

apidoc

37

NSAtools

2017-09-13 08:39:03 +08:00

口口相传

38

icycai

2017-09-13 08:53:06 +08:00 via Android

口口相传+1

39

kindjeff

2017-09-13 08:57:43 +08:00 via iPhone

传嫡不传庶，传长不传幼，传男不传女

40

justicelove

2017-09-13 09:01:48 +08:00

搜索就是 control + F

41

caizhendi

2017-09-13 09:13:38 +08:00

后台自己维护个文档

42

cnbattle

2017-09-13 09:15:02 +08:00

口口相传.gif

43

simonlu9

2017-09-13 09:16:24 +08:00

eo-linker

44

chocotan

2017-09-13 09:17:18 +08:00

一开始是口口相传，自从搭了 confluence 后大多用这个了

45

Clarencep

2017-09-13 09:19:11 +08:00

我司是我自己用 Laravel 写了一个基于 Markdown 的文档系统，支持文档模版，支持复制粘贴图片，支持全文检索，支持用户权限管理。开发用时约 3 天。

话说这种东西还是自己做的用着舒服：）

上家用的 confluence 也很不错，不过现在这家没买，懒得搞破解版，所以还是自己动手丰衣足食。

46

lrh3321

2017-09-13 09:20:48 +08:00

口口相传+1

忘记了就去看聊天记录

47

timelessg

2017-09-13 09:29:45 +08:00 via Android

当然是微信了

48

vlean

2017-09-13 09:42:46 +08:00

@49degree RAP+1 +wiki

49

a7063888

2017-09-13 09:47:21 +08:00

@lrh3321
口口相传+聊天记录还是老哥稳

公司用 confluence

50

keepcleargas

2017-09-13 10:35:01 +08:00

slate + git

51

xiaowangge

2017-09-13 10:40:27 +08:00

口口相传+聊天记录

+1

52

vjnjc

2017-09-13 10:40:29 +08:00

wiki +1
swagger 的话不用他一整套不方便吧，还不如 wiki 上格式写规范点

53

teaaa

2017-09-13 10:43:50 +08:00

wiki +1
强迫症觉得必须有统一的接口文档啊
很方便高效啊
要不怎么推锅

54

WendellSun

2017-09-13 10:44:11 +08:00

口口相传+1

55

noNOno

2017-09-13 10:45:55 +08:00

confluence + 1

56

imherer

2017-09-13 10:46:18 +08:00

https://github.com/lord/slate 这个。支持搜索

57

codeyung

2017-09-13 10:47:41 +08:00

confluence 自写（之前项目都是自己 wiki 手写的很多）现在的 swagger 做模块服务时候用

58

fork3rt

2017-09-13 10:51:51 +08:00

swagger 或者手写 markdown

59

liuqitoday

2017-09-13 11:20:08 +08:00

口口相传+1

60

YiBaZhuangYuan

2017-09-13 11:22:50 +08:00

GitLab

61

my3157

2017-09-13 11:24:23 +08:00

昨天正好也在看这个, 转了一圈, 目前做 api 文档管理的有 nei easyapi eolinker apizza RAP , 体验了其中 eolinker 和 apizza, 最后选择了 postman, 不但能做文档, 顺便还写了 api 测试 , 免费档已够用

62

lifeforwater

2017-09-13 11:31:41 +08:00

小幺鸡

63

zjsxwc

2017-09-13 11:33:51 +08:00 via Android

邮件

64

xxdd

2017-09-13 11:44:08 +08:00

看我口型

65

orancho

2017-09-13 11:53:53 +08:00

@lgh

如果你用 gRPC 的话，可以直接将 proto 文件中定义的 service 名传给 invoke 函数。对于使用 protobuf 的 RESTful API，我司一般的方法是在对应的 message 前的注释中写上对应的 URI。

66

leaybc

2017-09-13 11:58:02 +08:00

我在用 swagger 然后配合第三方的 UI . 感觉挺好的

67

silov

2017-09-13 12:01:18 +08:00

markdown 丢 git 上 ==

68

Simcyber

2017-09-13 12:30:31 +08:00

口口相传+1024

69

MrXiong

OP

2017-09-13 12:42:58 +08:00

@leaybc 有啥 ui 推荐

70

ezreal

2017-09-13 12:52:06 +08:00 via iPhone

口口相传

71

laudukang

2017-09-13 13:00:38 +08:00

口口相传

72

Vindroid

2017-09-13 13:02:24 +08:00

GitLab

73

qscqesze

2017-09-13 13:03:48 +08:00

口口相传，最多写个 wiki 解释一下

74

zhygkx

2017-09-13 13:06:48 +08:00

http://springfox.github.io/springfox/

75

dreamwar

2017-09-13 13:08:49 +08:00

心灵感应

76

owenliang

2017-09-13 13:09:46 +08:00

gitlab README

77

c0878

2017-09-13 13:12:23 +08:00

mkdocs

78

l00t

2017-09-13 13:17:19 +08:00

Excel + svn

79

siteshen

2017-09-13 13:27:44 +08:00

我们公司使用的 swagger，不过默认的“先设计好 *所有* API 格式，再生成代码模版”的方式并不适合我们（因为随时需要增加新的 API 和扩展现有的 API ），我们的使用方式如下：

1. python/go 代码按正常逻辑写，如：
// method, url, input format, output format
routes = [("POST", "/me/update", UpdateMeForm, MeResponse, ["tag1", "tag2", ...])]

2. 自定义函数 ToSwaggerJSON(method, url, request_form, response_object) 生成对应的 swagger.json 文件，然后交给 swagger-ui 处理其余事情；

3. 客户端在浏览器查看 API 文档，几乎没有进行过 API 问题的沟通。

ps: 最大的难点在于 ToSwagger() 函数，python/go 都没找到合适的库，花了不少的时间（印象中 python/go 各一周？），自己查看 swagger 文档实现了部分接口格式。

80

Lucups

2017-09-13 13:29:52 +08:00

@feiyuanqiu 改好了提 pull request 回馈社区~~