首页   注册   登录
V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
华为云
V2EX  ›  程序员

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

  •  1
     
  •   aschoolboy · 90 天前 · 7765 次点击
    这是一个创建于 90 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

    116 回复  |  直到 2018-07-23 11:33:02 +08:00
    1  2  
        101
    NotFamous   89 天前
    居然没人提 kancloud
        103
    chinvo   89 天前
    对外 API 是用 API Star 汇总或者开发的,自带文档

    内部用 Postman / Paw,开发自己测接口也很方便
        104
    Muyiafan   89 天前
        105
    classyk   89 天前 via iPhone
    还有用 doxygen 的吗
        106
    ferock   89 天前
    @CabalPHP 这个文档是用什么生成的?
        107
    ferock   89 天前
    明白了,docsify

    好项目!
        108
    jayliao   89 天前
    eolinker
        109
    kkeybbs   89 天前 via iPhone
    grpc protobuf3 注释加 swagger,和前端也是 grpc,用了层转换的 grpc gateway
        110
    Zzdex   89 天前   ♥ 1
    累死累活整理完文档,问我接口在哪,参数是啥,返回的啥意思,
    服!
        111
    samirmw   89 天前 via Android
    Raml
        112
    alta   89 天前
    支持多人同时编辑的文档很多啊,比如腾讯文档,石墨文档,编辑 api 文档个完全没有问题啊,并且可以查看编辑修改时间,内容和用户。。有免费的版也有收费版。。。
        113
    chenqimiao   88 天前
    swagger 吧。随版本更新,结合 git,还可以查看各个版本对应的接口文档
        114
    kurtchen   88 天前
    有个开源插件叫 showdoc ;有接口文档模板;做出来的样式和看云的差不多; ui 也好看关键是免费部署快
        115
    TommyLemon   88 天前
    @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"/>
        116
    TommyLemon   85 天前
    @Zzdex 所以你需要 APIJSONAuto 这种自动化的文档,一行代码都不用写,看上面的回复
    1  2  
    关于   ·   FAQ   ·   API   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   2248 人在线   最高记录 3762   ·  
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.1 · 27ms · UTC 12:20 · PVG 20:20 · LAX 05:20 · JFK 08:20
    ♥ Do have faith in what you're doing.
    沪ICP备16043287号-1