Swagger框架学习

1.Swagger的定义

Swagger 是一个规范和完整的API文档对接框架，通过设置对应的注解，扫描相关的代码来生成描述文件，进而生成与代码和对应代码描述一致并且是可视化 RESTful 风格可以传入不同参数进行调用的接口文档。这种通过代码生成的接口文档，由于是通过对应注解生成和代码保持一致，所以在持续迭代的项目中无论如何修改参数方法，接口文档都会对应作出相同的修改，这使得接口文档变得具有实时性并且能够非常高效的传递项目中的接口的实际情况。

1.1 Swagger官网也提供了如下几种开源工具，可以集成配置达到所需求的效果：

Swagger Codegen: 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。

Swagger UI:提供了一个可视化的UI页面展示描述文件，可以直观的对添加swagger注解的接口进行查询，参数调用，查看回调结果等一系列操作。

Swagger Editor: 编辑器的编辑Swagger描述文件的编辑器，提供了在线编辑器和本地部署编辑器两种方式并且可以实时预览描述文件。

Swagger Inspector:用于Swagger文档的在线调用调试，相对于Swagger Ui中的调试，会返回更多的信息并且可以保存你请求的实际请求参数等信息。

Swagger Hub：集成了上面所有项目的各个功能可以以项目和版本为单位，将描述文件上传到Swagger Hub中，相当于一个整合平台。

2.Swagger的使用

2.1 添加Maven依赖

io.springfox springfox-swagger2 XXX io.springfox springfox-swagger-ui XXX com.github.xiaoymin swagger-bootstrap-ui XXX

在生成swagger文档时，如何和代码保持一致，其实就是通过设置的各种注解来实现的。

@Api注解是对请求类的说明，一般常用参数有：

tags：用于描述这个请求类，并且标识这个请求类的情况，标记可用于按资源或任何其他限定符对操作进行逻辑分组；

value：在未使用tags的情况下将用于为这个类的描述情况标记，如果有tags的设置，则该值将被忽略。

@ApiOperation注解是对需要展示接口的标记，常用参数有；

value：提此供接口的简要描述或者操作说明；

notes：对该接口操作的详细描述说明。

@ApiResponse注解描述该接口的返回值详细情况，常用的参数有：

code：返回成功的成功数字标识；

message：返回成功的描述；

response:描述返回值中的响应类的类型。

@RequestParm注解是描述该接口的请求的参数。

@Api(tags="具体controller描述") @RestController public class TestController { @GetMapping("/test") @ApiOperation("具体方法的描述") @ApiResponse(code=0,message="查询成功",response=XXX.class) public String test(@RequestParam String parm){ ... ... } }

API

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。