Swagger构建伟大的API

Swagger构建伟大的API

Swagger构建伟大的API

手写Api文档的几个痛点：

  1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。

  2. 接口返回结果不明确

  3. 不能直接在线测试接口，通常需要使用工具，比如postman

  4. 接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

官网介绍：

Swagger Inspector：测试API和生成OpenAPI的开发工具。Swagger Inspector的建立是为了解决开发者的三个主要目标。

  1. 执行简单的API测试

  2. 生成OpenAPI文档

  3. 探索新的API功能

我的理解Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。简单来说，Swagger是一个功能强大的接口管理工具，并且提供了多种编程语言的前后端分离解决方案。根据我的使用，当然我只是最简单的使用，我感觉Swagger有以下几个优点：

  1. Swagger可以整合到代码中，在开发时通过注解，编写注释，自动生成API文档。

  2. 将前端后台分开，不会有过分的依赖。

  3. 界面清晰，无论是editor的实时展示还是ui的展示都十分人性化，如果自己仅仅用markdown来编写，又要纠结该如何展现，十分痛苦。

  4. 支持Json和yaml来编写API文档，并且支持导出为json、yaml、markdown等格式。

  5. 如果编写好了API了，可以自动生成相应的SDK，没错，可能你的API接口代码还没有开始写，它就能帮你制作相应的SDK了，而且支持几乎所有主流编程语言的SDK。


注意参考文献：swagger 学习笔记   SpringBoot整合Swagger2   SpringBoot,Maven构建SwaggerAPI文档