swagger使用详解

swagger简介

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

swagger的优势

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
Swagger 可以生成服务端代码和客户端SDK代码用于各种不同的平台上的实现。
Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
Swagger 有一个强大的社区，里面有许多强悍的贡献者。
Swagger编写语言统一、风格统一、可读性高
Swagger根据查看到的接口，我们不仅能看到接口的链接串、参数、返回值等各种信息，我们还可以真实的对服务器进行请求，查看真实的交互，大大减少了同事之间的交互成本

部署自己的swagger API

1、从git上clone：git clone https://github.com/swagger-api/swagger-ui.git；
2、修改访问.html url地址为相对路径（保证能访问到json配置文件）;
3、修改.json文件；
4、浏览器调试程序，swagger接口地址+‘/’+对应html文件

json文件各参数祥解

1、swagger：swagger的版本号；
2、info：接口相关信息。具体：title 接口标题；version：接口版本；termsOfService：服务地址；description：描述；contact：接口提供者联系方式
3、host：接口host地址；
4、base：接口路径地址；
5、可以使用tags设置多个标签的属性:name为唯一标识名称，对应让接口属于哪个tags标签设置对应的tags属性为该名称即可；description：为该标签的描述；
6、schemes：使用哪种请求协议；
7、paths：具体接口列表。首先，接口地址；其次，数据提交方式（post、get、put、delete等）第三，tags 对应属于哪个标签；summary：接口名称；description：接口描述；
author：作者；operationId操作id：唯一标识；parameters请求参数列表：name，参数名；in：参数类型（path、query、body、header、formData），description：参数描述，required：是否必须，type:数据类型(string,number,integer,boolean,array,object)，defalut：默认值.
responses：返回信息

针对跨域

1、swagger使用 CORS（跨源资源共享）来解决跨域问题，这样的话，就只需改动服务器端代码，而无需改动客户端代码，而且 CORS 支持各种请求类型。
2、在服务端添加跨域响应头部：Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Key, Authorization