未分類
20 7 月 2020

开发了一个方便写 Swagger 文档的项目

开发了一个方便写 Swagger 文档的项目

資深大佬 : cai314494687 10

一开始准备写个 API 项目，结果发现没有一个写 Swagger 方式文档的工具，不要提在代码里面用注释的方式生成 Swagger 文档，我觉得这种方式特别恶心。

所以我自己手动造了一个轮子，仓库：

https://github.com/cashwarden/docs

已经实现 Github Action CI，编写 API，配合 Github Pages 实现自动更新文档。

大佬有話說 (7)

  • 資深大佬 : cweijan

    你这个的作用是啥? 在代码用注释生成文档是很好的方式, 我想你指的是注解

  • 主 資深大佬 : cai314494687

    @cweijan #1 我指的是用注释的方式生成 Swagger API 文档，感觉 1 是自由度不够高，2 是注释的格式非常不友好，往往要写很长的一段注释，而且注释的内容是不能被 IDE 格式化的，我觉得非常不友好。

  • 主 資深大佬 : cai314494687

    @cweijan #1 忘了说作用了，这个工具就是给你方便写 Swagger API 文档的，看看 openapi 目录就知道了。

  • 資深大佬 : cweijan

    @cai314494687 看了下, 说实在并不看好, 接口如果发生变动, 就和文档不同步了, 如果用注释的方式就可以及时更新了
    swagger 有 https://github.com/Willing-Xyz/RestDoc
    yapi 有 https://plugins.jetbrains.com/plugin/index?xmlId=com.itangcent.idea.plugin.easy-yapi

  • 主 資深大佬 : cai314494687

    @cweijan #4 不好意思，我不用 Java，我这个跟语言无关。

    我这个只是一个小工具而已，我自己用起来方便，顺便分享给大家，大家用得着就更好了，用不着就算了，反正就花了 1 天时间开发的。

  • 資深大佬 : raaaaaar

    我觉得把写接口文档和接口测试联系起来是比较好的方式，比如 postman 生成文档就不错，方便管理接口，也方便更新

  • 資深大佬 : yanshenxian

    @raaaaaar +1 就喜欢这种无侵入的 就是更耗费精力
    如果是 java spring 有个 spring rest doc