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

2015年06月18日 14:40:52

声明


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

我的文档经历

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


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

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


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

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

app后端开发系列文章目录

Swagger UI 使用

简介,基于Swagger UI其实是纯static的web程序,仅仅在页面加载的时候,调用http连接,获取yaml字符串或者json字符串,这里我将yaml文件和放到静态项目中,并使用tomcat启...
  • gsying1474
  • gsying1474
  • 2016年02月18日 21:03
  • 11759

Java Restfull API 文档生成 Swagger UI

原文地址:http://javatech.wang/index.PHP/archives/74/ 笔者目前正在搭建一套API服务框架,考虑到客户端能够更方便的调用API服务(这里说的更方便是指避...
  • zhangqipu000
  • zhangqipu000
  • 2017年03月06日 18:15
  • 5310

Swagger 自定义UI界面

Swagger 自定义UI界面 Swagger简单介绍 如何使用Swagger 添加自定义UI界面 使用swagger-ui-layer...
  • tuposky
  • tuposky
  • 2017年09月13日 14:11
  • 3723

SpringMVC+Swagger UI生成可视图的API文档(详细图解)

SpringMVC+Swagger生成文档详细图解,以及遇到的异常处理
  • u011499992
  • u011499992
  • 2016年12月04日 19:16
  • 26314

springmvc 配置swagger ui 生成接口文档

swagger version :1.0.2 1.pom.xml com.mangofactory swagger-springmvc 1.0.2 com...
  • u013796473
  • u013796473
  • 2017年07月12日 17:54
  • 211

SwaggerUI自动生成API文档(SwaggerUI+SpringBoot)

SwaggerUI+SpringBoot 访问地址 http://localhost:9330/v1/swagger-ui.html#/ Maven依赖 io.sp...
  • zhe1110
  • zhe1110
  • 2016年11月02日 10:29
  • 5732

swagger环境的搭建(swagger-editor|swagger-ui)

swagger环境的搭建swagger-editor、swagger-ui
  • ron03129596
  • ron03129596
  • 2016年12月10日 17:18
  • 18776

Swagger简介

前言 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码,了解更多内容,见参考资料...
  • aaa333qwe
  • aaa333qwe
  • 2018年01月16日 11:29
  • 16

Windows 搭建swagger editor 和swagger ui

一,搭建swagger editor 要求:node.js环境 1,安装node.js 2, npm install; 3, git clone https://github.com/s...
  • u013796473
  • u013796473
  • 2017年07月12日 18:20
  • 961

手把手带你入门之Swagger UI

关于Swagger UI,从官网找来一段介绍。 简单的来讲, Swagger UI就是API文档生成和测试利器。 Swagger UI is a dependency-freecollection o...
  • chndata
  • chndata
  • 2016年01月04日 15:33
  • 8456
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:app后端开发一:swagger-ui教程-构建api接口文档工具
举报原因:
原因补充:

(最多只允许输入30个字)