开源的API文档工具框架——Swagger简介

　　初次接触Swagger是在2017年5月，当时公司正好要对整套系统架构进行重新设计，有同事推荐用这个技术框架来规范后台接口的API文档。当时因为架构重构，涉及改造的技术点太多，一时也就没太多精力，把Swagger暂时放下了。对于API文档我们就自己定义了一个模板，统一要求开发人员把文档写在tower上了。

现在回头来看，存在这么几个问题：

1. 文档编写及修改的及时性不够，由于API在开发及测试过程中经常会有调整，相应的文档不能及时得到修改。

2. 文档的规范性需要人为的检查来约束，增大了项目管理的工作量

3. 前端和测试人员对文档的理解有一个过程，有时需要频繁和后台开发人员进行交流，产生了一定的交流成本。

由于现在的互联网项目都是前后端合作的形式，前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，在这样的情况下，我又把注意力再次投向了Swagger。经过几天研究，大致有了比较清晰的认识，准备写几篇博客对这个技术进行一下说明。

Swagger这个单词做形容词是 “炫耀的；时髦的”  这样一个意思。官网地址：https://swagger.io，官网对其项目的定义是：

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.　　　　　　　　　　　　　　　　

中文意思是：Swagger是一个大型的API开发者的工具框架，该框架提出了一个编写OpenAPI的规范（命名为OAS），并且Swagger可以跨整个API生命周期进行开发，从设计和文档到测试和部署。

Swagger这个框架的原理：框架提出了一个文档规范OAS，且提供了相应的可视化编辑器可以编辑这个文档以及对文档格式进行校验，文档的存储格式可是XML或者JSON形式的文件（后面简称API元文件），围绕着API元文件框架提供了对API元文件进行可视化展示的工具，展示的时候可以自定义模板，展示的方式是浏览器的网页形式(也就是一个 可交互的web系统），并且支持对AIP接口的在线的交互测试。同时社区还开发了一些集成框架，以便让Swagger能和例如SpringMVC这样的框架很好的整合，通过在Controller上写注解就可以自动生成相应的API文档。更有意思的是Swagger还提供了根据API元文件生成客户端调用代码和服务端Stub代码的功能。

Swagger框架从宏观上来看，我个人觉得可以分为三部分：

• 提供了一个编写API文档的规范 ，称为OAS ，在规范中明确API的格式和一些编写要素
• 提供相关的工具，对API文档的编写提供辅助。主要是这么几个项目 Swagger Editor、Swagger UI、Swagger Codegen、Swagger Inspector。
• 提供对各种流行语言和框架的集成，例如集成SpringMVC 的 springfox 框架