app后端开发一：swagger-ui教程-构建api接口文档工具

梦里梦外; 2022-08-01 02:59 281阅读 0赞

# **声明** #

--------------------

之前写过关于app后端开发的一系列文章，那是我第一次做app后端开发，存在很多不足，本想好好修改一下，想想还是重新写吧，这样子也能让我博客文章看起来多一点嘛，万一以后找工作，别人一看我博客这么多内容，是不是很屌？  
这次文章先从构建resetful风格的api文档工具开始。没有一个好的文档工具，在app前端人员开发过程中会导致开发效率极低，而且时不时的，他们就来找你跟他们断点一下。

# **我的文档经历** #

> 这里先不讨论我的数据传输是否合理，仅仅以这些数据作为一个演示。后面会有专门的章节进行app数据传输加密的讲解。

--------------------

1.  在我第一次开发app后端的时候，使用的word文档，就是我先将所有数据格式定义好，会返回什么样的数据写好。前端人员照这个来进行开发。贴一张图吧：  
    ![这里写图片描述][20150618095704913]  
    *PS:存在的问题：①接口改动时，不易被识别。②维护困难，不便于查找。③前端开发不能进行测试。(如果还要写缺点，有5K+字可以写出来，就省略了哈)*
2.  在我开发第二个APP的后端时，先自己写了一个简易的app接口管理系统，用来后端发布接口，以及前端人员查看。效果如图：  
    ![这里写图片描述][20150618142603759]  
    *PS:优点：①如果有多个前端人员，可以保证大家看到的是同一份文档。②通过接口的版本标识，方便大家查看是否修改，优点等等省略。缺点：①不能够进行在线接口测试，需要借助poster插件。*
3.  现在给大家要推荐下我利用一天时间改造的swagger-ui的中文版了。本来英文就非常好了，只是为了了解一下这个东东，顺手给他改成中文版了，也做为自己第一个github的项目吧。还是先上效果图吧：  
    接口模块界面：  
    ![这里写图片描述][20150618143142609]  
    接口列表界面：  
    ![这里写图片描述][20150618143232062]  
    某个接口界面：  
    ![这里写图片描述][20150618143315458]

--------------------

OK，贴图到此为止啦，如果还没有看够的同学，给你们一个连接，自己去试试：  
swagger-ui中文版地址：[http://helei112g.github.io/swagger-ui/][http_helei112g.github.io_swagger-ui]

--------------------

相信经过刚刚的体验，不需要我说它的强大与便利了吧？不仅仅可以通过它立即进行在线测试，还可以根据返回的json它自动构建成model。便于你做决策。好处我就不说了，反正自从用了它，我们的前端腰不酸，腿也不痛了。写起代码来也精神了。

哦，最重要的，下载地址：  
[https://github.com/helei112g/swagger-ui][https_github.com_helei112g_swagger-ui]  
如果觉得不错，麻烦给个start吧，给我的鼓励一下下，谢谢！

[app后端开发系列文章目录][app]

[20150618095704913]: /images/20220731/dc0b62ca96cb4e35af007f833baa6062.png
[20150618142603759]: /images/20220731/220d01c4ba63487b839abf31d9ccf765.png
[20150618143142609]: /images/20220731/36e637bcb7284b9189e17c59181e2c6c.png
[20150618143232062]: /images/20220731/2cc7344f6fb04d6288fb57da758bfe50.png
[20150618143315458]: /images/20220731/1cafd6edaf2d481e9ded0cba17129ea9.png
[http_helei112g.github.io_swagger-ui]: http://helei112g.github.io/swagger-ui
[https_github.com_helei112g_swagger-ui]: https://github.com/helei112g/swagger-ui
[app]: http://blog.csdn.net/hel12he/article/details/47721209