各位公司的 API 接口文档是用的什么方式？

[aschoolboy]

之前公司的 API 接口文档写在 word 里，放在 github 上。
缺点很多，不能同时编辑，一同时编辑就冲突.
我趁一期项目结束，搭了个开源 API 接口网站：eolinker。
给师父看了，说可以，叫我把所有接口都牵进去了。准备让所有同事用了。
结果有的同事一看感觉不方便，说可以用 markdown 来写。
又安排我找个用 markdown 写的 api 文档模板

所以想问问大家的 api 接口文档是采用什么方式的？

[NotFamous]

居然没人提 kancloud

[chinvo]

对外 API 是用 API Star 汇总或者开发的，自带文档

内部用 Postman / Paw，开发自己测接口也很方便

[Muyiafan]

http://apidocjs.com/

[classyk]

还有用 doxygen 的吗

[ferock]

@CabalPHP 这个文档是用什么生成的？

[ferock]

明白了，docsify

好项目！

[jayliao]

eolinker

[kkeybbs]

grpc protobuf3 注释加 swagger，和前端也是 grpc，用了层转换的 grpc gateway

[Zzdex]

累死累活整理完文档，问我接口在哪，参数是啥，返回的啥意思，
服！

[samirmw]

Raml

[alta]

支持多人同时编辑的文档很多啊，比如腾讯文档，石墨文档，编辑 api 文档个完全没有问题啊，并且可以查看编辑修改时间，内容和用户。。有免费的版也有收费版。。。

[chenqimiao]

swagger 吧。随版本更新，结合 git，还可以查看各个版本对应的接口文档

[kurtchen]

有个开源插件叫 showdoc ；有接口文档模板；做出来的样式和看云的差不多； ui 也好看关键是免费部署快

[TommyLemon]

@feiyuanqiu
用 Swagger：
一个 Controller 得写一个 @Api 注解吧?
一个 GET 参数得写一个 @ApiParam 注解吧？
一个 Entity 得写一个 @ApiModel 注解吧？
Entity 的每个字段得分别写一个 @ApiModelProperty 注解吧？

然后就成了这样：
```java
@Api(value="用户 controller",tags={"用户操作接口"})
@RestController
public class UserController {
@ApiOperation(value="获取用户信息",tags={"获取用户信息 copy"},notes="注意问题点")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用户 id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
// userService 可忽略，是业务逻辑
User user = userService.getUserInfo();

return user;
}
}
```

```java
@ApiModel(value="user 对象",description="用户对象 user")
public class User implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty(value="用户名",name="username",example="xingguo")
private String username;
@ApiModelProperty(value="状态",name="state",required=true)
private Integer state;
private String password;
private String nickName;
private Integer isDeleted;

@ApiModelProperty(value="id 数组",hidden=true)
private String[] ids;
private List<String> idList;
//省略 get/set
}
```



用 APIJSONAuto，一行代码都不用写，直接用数据库表和字段属性自动生成文档哦

2. User
说明:
用户公开信息表。
对安全要求高，不想泄漏真实名称。对外名称为 User

字段:
名称 | 类型 | 最大长度| 详细说明
id | Long | 15 | 唯一标识
sex | Integer | 2 | 性别：0-男 1-女
name | String | 20 | 名称
tag | String | 45 | 标签
head | String | 300 | 头像 url
contactIdList | List | 不限 | 联系人 id 列表
pictureList | List | 不限 | 照片列表
date | Timestamp | 不限 | 创建日期

创作不易，GitHub 右上角点 Star 支持下吧，谢谢^_^
<img src="/github.com/TommyLemon/APIJSON"/>

[TommyLemon]

@Zzdex 所以你需要 APIJSONAuto 这种自动化的文档，一行代码都不用写，看上面的回复

[balabalaguguji]

试下 https://easydoc.xyz ，应该很适合你