API 文档大家是怎么生成的?

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

这是一个创建于 1338 天前的主题，其中的信息可能已经有所发展或是发生改变。

java 写的 web 服务, 要给前端提供接口文档, 问下大家都是怎么生成的?
现在业内实践用的都是啥?

第 1 条附言 · 2021-03-10 17:33:29 +08:00

看来主流还是 swagger 和 yapi 啊

俺看了一下, 俺的服务不到 10 个接口, 也很简单

所以, 最终, 俺用的方式是

使用 markdown, 手工

感谢铁子们推荐, 等接口复杂了, 再研究你们的工具

文档

生成

API

Java

84 条回复 • 2021-07-22 23:09:17 +08:00

alanhe421

2021-03-10 09:41:47 +08:00

swagger

sunziren

2021-03-10 09:49:18 +08:00

用过楼上的，挺好的

gageshan

2021-03-10 09:49:53 +08:00

https://github.com/YMFE/yapi

knightdf

2021-03-10 09:50:51 +08:00

openapi, swagger

wolfie

2021-03-10 09:51:31 +08:00

md 手写，生成的除了自己很难看，而且涉及到字段改动怎么标注。

lungank

2021-03-10 09:52:14 +08:00

swagger

rationa1cuzz

2021-03-10 09:55:15 +08:00

难道就我一个人手写吗？

hanssx

2021-03-10 09:56:48 +08:00

如果 python 的话，fastapi 很不错。

zlhsvc

2021-03-10 09:56:55 +08:00

手写，之前用过脚本总觉得差了点

yiqiao

2021-03-10 09:57:06 +08:00

swagger 能够快速生成。
showdoc

acmore

2021-03-10 09:57:33 +08:00

swagger
Java 生态下也可以考虑 Spring Rest Docs

balabalaguguji

2021-03-10 09:59:25 +08:00

可以用易文档编写 https://easydoc.xyz ，它也可以一键生成文档，也可以从注释生成文档。预览效果： https://www.easydoc.xyz/s/17790664

截图
https://i.loli.net/2021/03/10/jVQdKMkJ4FPevui.png

liuzhaowei55

2021-03-10 10:01:18 +08:00 via iPhone

手写

bigpigeon

2021-03-10 10:03:12 +08:00

swagger

bigpigeon

2021-03-10 10:04:09 +08:00

写了一个通过 go 框架生成 swagger 代码的 api，只要实现 api 就能自动生成 swagger

SjwNo1

2021-03-10 10:06:49 +08:00

手写+1

sss495088732

2021-03-10 10:10:15 +08:00

yapi docker 手写

jowan

2021-03-10 10:14:20 +08:00

swag

zhaorunze

2021-03-10 10:16:42 +08:00

我还以为手写了个框架，仔细一想，可能是手写文档。。。

ghouleztt

2021-03-10 10:19:02 +08:00

swagger

Molita

2021-03-10 10:20:22 +08:00

swagger 然后用 redoc 展示

15190049162

2021-03-10 10:20:45 +08:00

swagger+插件直接变 doc

mcfog

2021-03-10 10:28:27 +08:00

重要的不是怎么生成，而是数据源在哪里，怎么管理

h82258652

2021-03-10 10:29:44 +08:00

swagger，部分生成不了的用 docfx

oneend

2021-03-10 10:32:23 +08:00

只有我用 gitbook 吗？

www5070504

2021-03-10 10:34:11 +08:00

swagger 只要增加几行注释很好用..

a62527776a

2021-03-10 10:36:22 +08:00

apidoc

Rekkles

2021-03-10 10:36:49 +08:00

yapi

star7th

2021-03-10 10:37:34 +08:00

https://github.com/star7th/showdoc

journalistFromHK

2021-03-10 10:48:07 +08:00

上一家公司，老板写 java，啥是文档？不存在的，自己去看 controller 吧

so1n

2021-03-10 10:49:02 +08:00

自己写了一个库来自动生成 https://github.com/so1n/pait

henryhu

2021-03-10 11:18:24 +08:00

apidoc

UN2758

2021-03-10 11:20:37 +08:00

@hanssx #8 我记得 fastapi 用的也是 swagger

KisekiRemi

2021-03-10 11:21:41 +08:00

对接的给我一个 swagger

cat007

2021-03-10 11:25:34 +08:00

swagger+yapi

AngryPanda

2021-03-10 11:27:09 +08:00

md 手写、YAPI

evam

2021-03-10 11:31:20 +08:00

postman 自己调试接口，然后 postman 分享，coding 自动生成

egfegdfr

2021-03-10 11:39:48 +08:00

smart-doc
感觉 swagger 的侵入性太强了

jorneyr

2021-03-10 11:41:09 +08:00

不喜欢 swagger 这种污染源码的工具，更喜欢用 yApi 这种类似的工具进行管理。

xuanbg

2021-03-10 11:54:45 +08:00

@wolfie md 手写+1，也就是模版上面复制粘贴，一点都不费事。swagger 实在是太丑

monkeyWie

2021-03-10 12:01:01 +08:00

swagger 然后自动同步到 yapi

scxiazi

2021-03-10 12:07:31 +08:00

restdoc

putaozhenhaochi

2021-03-10 12:16:20 +08:00

借楼问下，各位是先定义接口还是先写代码

MarioLuo

2021-03-10 12:33:16 +08:00

YapiIdeaUploadPlugin IDEA 插件基于 JavaDoc 注释生成文档，上传到 yapi 中.

xnotepad

2021-03-10 13:05:58 +08:00

自己写了个 https://apidoc.tools

chogath

2021-03-10 13:25:13 +08:00

swagger + yapi，永远滴神

newmlp

2021-03-10 13:31:18 +08:00

md 手写

offswitch

2021-03-10 13:50:56 +08:00

@putaozhenhaochi 通常的说法是先写定义再写代码，不过大部分公司根本就没这要求，爱咋咋

alienx717

2021-03-10 13:57:36 +08:00

md 手写

XCFOX

2021-03-10 14:09:00 +08:00

目前用过最舒服的是 GraphQL 。文档和接口无缝结合。接口还是强类型的。前端能直接根据 graphql 接口地址生成接口类型

20200924

2021-03-10 14:18:37 +08:00

作为前端人员，感觉看 yapi 比看 swagger 舒服很多

justin2018

2021-03-10 14:44:07 +08:00

每次 API 有啥修改就发一份 word 文档

真是不好吐槽

54xavier

2021-03-10 14:44:36 +08:00

swagger

sannyzeng

2021-03-10 14:59:40 +08:00

yapi

fuyangyishi0

2021-03-10 15:02:23 +08:00

没人用 RAP 吗

Gunn27

2021-03-10 15:06:47 +08:00

https://apicat.net

guiling

2021-03-10 15:16:48 +08:00

yapi

qW7bo2FbzbC0

2021-03-10 15:23:28 +08:00

因为 go 没有便捷的 swagger 工具，我转 spring 这种插件成熟的框架了

yang2048

2021-03-10 15:39:03 +08:00

swagger 或者 knife4j

YadongZhang

2021-03-10 15:52:02 +08:00

RESTful API，只有我用 Postman 写文档吗。。。

salenpeng

2021-03-10 15:57:22 +08:00

swag /:狗头

hakr

2021-03-10 16:07:14 +08:00

@YadongZhang #60 俺也用...

freebird1994

2021-03-10 16:17:52 +08:00

swagger + yapi

liuw666

2021-03-10 16:45:54 +08:00

写 protobuf 然后生成 swagger

liuw666

2021-03-10 16:47:59 +08:00

使用 protobuf 定义，只要想改接口参数，proto 就必须修改，swagger 肯定也是最新的

ERRASYNCTYPE

2021-03-10 17:20:09 +08:00

实习生写

asanelder

2021-03-10 17:32:09 +08:00

@ERRASYNCTYPE #66 铁子, nb

m1ch3ng

2021-03-10 18:32:51 +08:00

smart-doc，靠 javadoc 就能自动生成

liuzhihang

2021-03-10 19:22:57 +08:00

IDEA 插件 Doc View 纯 markdown 。不知道能不能满足你的需求。也欢迎 v2 小伙伴提 PR

https://github.com/liuzhihang/doc-view

![aF2vk5-L5pmGt]( https://cdn.jsdelivr.net/gh/liuzhihang/oss/pic/article/aF2vk5-L5pmGt.png)

Cbdy

2021-03-10 19:37:33 +08:00 via Android

手写

liuzhihang

2021-03-10 19:51:11 +08:00

发不出来图…… 看链接吧 https://plugins.jetbrains.com/plugin/15305-doc-view

noyidoit

2021-03-10 20:02:41 +08:00

postman......

dcatfly

2021-03-10 21:54:48 +08:00

yapi 竟然有 1k+的 issue 没关闭，最近在用它内部的组件，代码写的一言难尽。。让我觉得这个项目还没死也是不容易。。

vfxx

2021-03-10 21:55:19 +08:00

@star7th 必须推荐 showdoc，用过的都说好。

ArrayBuffer

2021-03-11 09:15:55 +08:00

我是前端, 对我来说最好的还是 `swagger` / `graphql`; `swagger` 是比较成熟的, 但对于阅读者来说还是有些地方体验不是很好, 为此我写了个脚本 greasyfork.org/zh-CN/scripts/401581, `graphql` 我也写了 greasyfork.org/zh-CN/scripts/416677