开源的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 框架