swagger 返回json字符串_Swagger、knife4j和YApi

摘要

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

下面介绍三款在线文档项目。

一、Swagger是什么？它能干什么？

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。

@Api //：修饰整个类，描述Controller的作用@ApiOperation //：描述一个类的一个方法，或者说一个接口@ApiParam //：单个参数描述@ApiModel //：用对象实体来作为入参@ApiProperty //：用对象接实体收参数时，描述对象的一个字段@ApiResponse //：HTTP响应其中1个描述@ApiResponses //：HTTP响应整体描述@ApiIgnore //：使用该注解忽略这个API@ApiError //：发生错误返回的信息@ApiImplicitParam //：一个请求参数@ApiImplicitParams //：多个请求参数

@Api修饰整个类，描述Controller的作用

@ApiOperation

用于描述一个方法或者接口

可以添加的参数形式：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”)

@ApiParam单个参数描述

@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”)

@ApiImplicitParam 一个请求参数

@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”)

@ApiOperation(value = “根据用户名获取用户的信息”,notes = “查询数据库中的记录”,httpMethod = “POST”,response = String.class)
@ApiImplicitParam(name = “userName”,value = “用户名”,required = true,dataType = “String”,paramType = “query”)
4.5、@ApiImplicitParams 多个请求参数

参数和@ApiImplicitParam一致，只是这个注解可以添加多个参数而已

2、knife4j

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，前身是swagger-bootstrap-ui，取名kni4j是希望她能像一把匕首一样小巧、轻量、并且功能强悍!

knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展，由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式，在微服务架构下显的很臃肿,因此项目正式更名为knife4j。

更名后主要专注的方面

• 前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活

• 提供专注于Swagger的增强解决方案，不同于只是改善增强前端Ui部分

功能特性

简洁

基于左右菜单式的布局方式，是更符合国人的操作习惯吧，文档更清晰…

个性化配置

个性化配置项，支持接口地址、接口description属性、UI增强等个性化配置功能…

增强

接口排序、Swagger资源保护、导出Markdown、参数缓存众多强大功能…

3 、YApi

YApi是高效、易用、功能强大的API管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。YApi在Github上已累计获得了18K+Star，具有优秀的交互体验，YApi不仅提供了常用的接口管理功能，还提供了权限管理、Mock数据、Swagger数据导入等功能，总之功能很强大！

YApi结合Swagger使用果然很强大！之前使用Postman结合Swagger使用时，文档查看、自动同步的问题都得到了解决，为了保证我们API文档访问的安全性还提供了权限管理功能。当API数据格式定义好后，Mock功能让前端无需后台实现也可以调试接口。不过对于JSON格式支持有点偏弱，要是能对JSON数据进行折叠显示就更好了！

参考资料

官方文档：https://hellosean1025.github.io/yapi/documents/index.html

项目源码地址

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-swagger