【工具使用】API表达工具----swagger

前言

   Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。

叙述

什么是API

   API（Application Programming Interface,应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

那么API和swagger有什么关系呢

  Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。 

Swagger包括库、编辑器、代码生成器等很多部分

Swagger Editor:

一个致力于基于Swagger的API的开源编辑器，可以描述和记录API。

作用：

（1）运行在任何地方：编辑器可以在任何开发环境中工作，无论是在本地还是在网络中

（2）可以随时进行反馈：验证Swagger合规性的语法，因为您可以使用简明的反馈和错误处理来编写它

（3）即时可视化：以可视化方式呈现API规范，并在定义API的同时与API进行交互

（4）智能自动完成：用智能和智能的自动完成功能更快地编写语法

（5）完全可定制：易于配置和自定义任何东西，从行距到主题

（6）构建：为每个流行语言的API生成服务器存根和客户端库

swagger codegen

   使用Swagger Codegen，以更快的速度构建API并改善每种流行语言中OpenAPI定义的API的消耗。Swagger Codegen可以通过从OpenAPI规范生成服务器存根和客户端SDK来简化构建过程，因此您的团队可以更好地关注API的实现和采用

作用：

（1）生成服务器：通过生成超过20种不同语言的样板服务器代码，消除繁琐的管道和配置

（2）改善API消耗：以超过40种不同语言生成客户端SDK，供最终开发人员轻松与您的API集成

（3）不断改进：Swagger Codegen总是随着编程世界的最新和最大的变化而更新

Swagger UI

  Swagger UI允许任何人  -  无论是你的开发团队还是你的最终用户 - 都可以在没有任何实现逻辑的情况下对API资源进行可视化和交互。它是通过Swagger规范自动生成的，可视化文档使得后端实现和客户端消费变得容易。

作用：

（1）无依赖关系：在任何环境中托管您的Swagger用户界面

（2）人性化：允许最终开发人员轻松地进行交互，并尝试您的API公开的每一个操作，以方便使用

（3）易于导航：利用整齐分类的文档快速查找和使用资源和端点

（4）所有浏览器支持：Swagger UI可以在所有主流浏览器中使用，满足各种可能的场景

（5）完全可定制：使用完整的源代码访问方式，按照您想要的方式调整和调整Swagger UI

 

swagger inspector

  Swagger Inspector是一个超快的API测试工具，可以轻松调用和验证基于REST，GraphQL和SOAP的Web服务，以确保它们正常工作。将您的开发工作流程无缝集成到自动保存测试历史的能力中，并立即从REST测试生成OpenAPI定义。

作用：

（1）不要让手动测试、减慢你的速度：立即在云上测试您的API，而无需繁琐的设置和配置。

（2）所有的API，易于测试：无论是REST还是SOAP，OpenAPI或RAML，Inspector都能简化所有API的手动测试。

（3）无论何时何地，测试您的API：随时随地保存您的测试并访问它们，这样您就可以随时随地拿起测试流程。

小结：

  具体的swagger每一部分如何应用呢，请看一下链接（超级棒哦）

Intro to API documentation with Swagger

How to use swagger online editorIntro to API documentation with Swagger

YAML tutorial How to use swagger online editorIntro to API documentation with Swagger

Open API specification summaryYAML tutorial How to use swagger online editorIntro to API

how to install and setup swagger

How to use swagger-ui-dist

gulp task automationhow to install and setup swagger locallyOpen API specification summaryYAML tutorial How to use swagger online editorIntro to API 

crash course and summarygulp task automationhow to install and setup swagger locallyOpen API specification summaryYAML tutorial How to