解放双手 告别手写API

前言

脑子一热开了个公众号,来记录下工作生活中遇到的一些问题。

起因

由于前端使用了typescript,后端api一更新,前端改动起来挺麻烦,他想后端提供api的schema,方便他自动生成。
schema正好可以来自动生成api,之前都是自己手写API文档,但是由于代码更新会由于未及时更新API文档而导致前端对接产生的差异。为了专心写代码,才开始了寻找自动化生成API文档的解决方案。
首先由于考虑到安全问题,所以直接排除掉来没有本地部署话的项目。不过说实话有些项目做的确实不错。比如:http://apizza.cc/ ,界面风格跟postman很像,在调试代码的时候就能一起完善好文档。但是并不适合我们。

选型

  • apidoc

    项目地址: https://apidocjs.com/example/
    文档不多,使用起来也很方便,直接在代码里加上注释直接就能生成api文档, 还支持调试。界面看起来也很清爽,支持分组,权限显示。

upload successful

  • swagger

    这款我纠结了很久,首先全自动化生成api文档,随着代码更新直接更新文档, 这个很符合我的需求,而且还支持Mock。但是研究了一天发现还是存在一些问 题。我使用的DRF,还不太完善,侵入式太强。

    https://github.com/marcgibbons/django-rest-swagger/issues/620
    The serializer_class attribute only works with GenericAPIView. That may not fit the particular use case of ?the login, though you could use the user model as the queryset.
    Otherwise, you can override the CoreAPI document to add Links to your schema (which then get converted to spec). See:
    http://www.django-rest-framework.org/api-guide/schemas/#schemagenerator

需要override,每个地方都需要这么添加。如果有人想用的话,可以参考这个项目,添加丢失的信息。https://github.com/tovmeod/drf-swagger-missing
upload successful

  • rap

    阿里的开源项目,还开源,支持Mock。可视化的添加api,总体来说挺不错,喜欢的人可以选择。
    upload successful

  • blueprint

    API Blueprint是使用Markdown来定义API的。同时API Blueprint与前面的Swagger一样也能提供可视化的文档界面与Mock Server的功能。风格我也挺喜欢,但是DRF不支持。也折腾了很久,通过Swagger转blueprint,但是在生成api。同样的原因,由于会丢失参数,需要自己override,所以放弃。不过界面挺不错 哈哈。
    upload successful

总结

总之东西很多,可是适合自己的并不多。最终还是选择了使用apidoc来进行文档生成,但是没有Mock功能。我们目前的现状是后端进度一直比前端快,所以Mock功能后面再看看吧。

upload successful

扫描关注公众号