「这是我参与2022首次更文挑战的第18天，活动详情查看：2022首次更文挑战」
现在都奉行前后端分离开发和微服务大行其道，前后端技术在各自道路上越走越远。 前后端唯一联系变成了API接口，API文档变成了前后端开发人员&测试人员联系的纽带。所以一款强大的Restful API文档就变得至关重要了。而目前在后端领域，基本上是Swagger的天下了。
Swagger是一款Restful 接口的文档在线自动生成、功能测试框架。一个规范和完整的框架，用于生成、描述、调用和可视化Restful 风格的Web服务，加上Swagger-UI，可以有很好的呈现。
Swagger是一组开源项目，其中主要项目如下：
- Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
- Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
- Swagger-js: 用于JavaScript的Swagger实现。
- Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
- Swagger-UI：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
- Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。
Swagger-UI 是一款Restful接口的文档在线自动生成+功能测试功能软件。 Swagger-UI 的官方地址：swagger.io/ Github上的项目地址：github.com/swagger-api… 官方提供的demo地址：petstore.swagger.io/
现在多数的项目开发中，网站和移动端都需要进行数据交互和对接，这少不了使用Restful编写API接口这种场景。 特别是不同开发&测试团队协作时，就更需要以规范和文档作为标准和协作基础。良好的文档可以减少沟通成本，达到事半功倍的效果。 有时对一些API说明的理解比较模糊，总想着能直接验证一下自己的理解就好了，而不是需要去项目写测试代码来验证自己的想法。即API文档应具备直接执行能力，这种能力类似word,wiki等是无法提供。Swagger-UI 就是这样一种利器，基于实现，倾向于在线文档和测试，使用和集成十分简单，能容易地生成不同模块下的API列表， 每个API接口描述和参数、请求方法都能定制并直接测试得到直观的响应数据。
目前官方提供的Swagger-UI 的使用方式主要有2种：
- 与不同的服务端代码集成，在服务端代码中嵌入SwaggerUI文档生成代码，部署时自动生成。
- 手动编辑对应的Json文档，该Json文档有其特定格式，相对比较复杂，手动编写难度比较大，可通过官方提供的在线编辑来实现。
pom依赖包
编写配置文件SwaggerConfig
添加文档内容(一般上是在Controller，请求参数上进行注解) 添加MyGetMethod类，这里演示两个Get请求
配置全局配置文件
启动项目
API首页路径：http://127.0.0.1:8888/swagger-ui.html 点击需要访问的API列表，查看接口详情，点击按钮测试
执行测试
服务端返回结果
Swagger使用的注解及其说明： @Api：用在类上，说明该类的作用。 @ApiOperation：注解来给API增加方法说明。 @ApiImplicitParams : 用在方法上包含一组参数说明。 @ApiImplicitParam：用来注解来给方法入参增加说明。 @ApiResponses：用于表示一组响应 @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- l code：数字，例如400
- l message：信息，例如"请求参数没填好"
- l response：抛出异常的类
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候） @ApiModelProperty：描述一个model的属性
对于其他注解，大家可自动谷歌，毕竟常用的就这几个了。有了swagger之后，原本一些接口请求需要Postman这样的调试工具来进行发起，而现在直接在页面上就可以进行调试了，是不是很爽？ 对于测试人员，有了这份API文档也是一目了然，不需要和后端多少沟通成本，按着API说明进行接口测试脚本开发即可。
本文主要是对Swagger的简单使用和Springboot集成进行了说明，详细的用法，可自行搜索相关资料下，这里就不阐述了。因为对于百分之八十之上的文档要求基本能满足了。最后，一定要在生产环境关闭Swagger,基于安全因素。
项目源码地址：
- github.com/zuozewei/bl…
版权声明：
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！
转载请注明出处，原文链接：https://www.xkablog.com/qdvuejs/80168.html