浅谈Swagger 之妙用

Swagger是一款容器平台开放API，对于某些人来说,或许有些陌生,但是对于互联网行业的从业者，不应该陌生,因为Swagger是一款用于管理各个界面的api接口的工具，比如登录接口，查找用户接口，添加用户接口，这些接口都需要通过一款平台或者工具管理.那么，swagger就是充当这样一个角色.

关于swagger上api接口结构如下:
1.Parameters 用于详细描写参数变量
2.Responses 响应代码
3.Response content type json/form/query/upload等
通常情况下，将Parameters输入之后，选择content type后，点击try out可看到response中显示的结果，如显示代码200，表示此接口通过，否则根据具体的响应状态码即可判断接口出错原因，如401权限不足，404找不到页面，500服务器内部错误等.在此

状态码列表如下(此处只涉及重要状态码):
1、语义有误，当前请求无法被服务器理解。除非进行修改，否则客户端不应该重复提交这个请求。
2、请求参数有误。
401 当前请求需要用户验证。该响应必须包含一个适用于被请求资源的 WWW-Authenticate 信息头用以询问用户信息。客户端可以重复提交一个包含恰当的 Authorization 头信息的请求。如果当前请求已经包含了 Authorization 证书，那么401响应代表着服务器验证已经拒绝了那些证书。如果401响应包含了与前一个响应相同的身份验证询问，且浏览器已经至少尝试了一次验证，那么浏览器应当向用户展示响应中包含的实体信息，因为这个实体信息中可能包含了相关诊断信息。
402 该状态码是为了将来可能的需求而预留的。
403 服务器已经理解请求，但是拒绝执行它。与401响应不同的是，身份验证并不能提供任何帮助，而且这个请求也不应该被重复提交。如果这不是一个 HEAD 请求，而且服务器希望能够讲清楚为何请求不能被执行，那么就应该在实体内描述拒绝的原因。当然服务器也可以返回一个404响应，假如它不希望让客户端获得任何信息。
404 请求失败，请求所希望得到的资源未被在服务器上发现。没有信息能够告诉用户这个状况到底是暂时的还是永久的。假如服务器知道情况的话，应当使用410状态码来告知旧资源因为某些内部的配置机制问题，已经永久的不可用，而且没有任何可以跳转的地址。404这个状态码被广泛应用于当服务器不想揭示到底为何请求被拒绝或者没有其他适合的响应可用的情况下。
服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理。一般来说，这个问题都会在服务器的程序码出错时出现。
501 服务器不支持当前请求所需要的某个功能。当服务器无法识别请求的方法，并且无法支持其对任何资源的请求。
502 作为网关或者代理工作的服务器尝试执行请求时，从上游服务器接收到无效的响应。
503 由于临时的服务器维护或者过载，服务器当前无法处理请求。这个状况是临时的，并且将在一段时间以后恢复。如果能够预计延迟时间，那么响应中可以包含一个 Retry-After 头用以标明这个延迟时间。如果没有给出这个 Retry-After 信息，那么客户端应当以处理500响应的方式处理它。 　　注意：503状态码的存在并不意味着服务器在过载的时候必须使用它。某些服务器只不过是希望拒绝客户端的连接。
504 作为网关或者代理工作的服务器尝试执行请求时，未能及时从上游服务器（URI标识出的服务器，例如HTTP、FTP、LDAP）或者辅助服务器（例如DNS）收到响应。 　　注意：某些代理服务器在DNS查询超时时会返回400或者500错误.
请求已成功，请求所希望的响应头或数据体将随此响应返回。
201 请求已经被实现，而且有一个新的资源已经依据请求的需要而建立，且其 URI 已经随Location 头信息返回。假如需要的资源无法及时建立的话，应当返回 '202 Accepted'。
202 服务器已接受请求，但尚未处理。正如它可能被拒绝一样，最终该请求可能会也可能不会被执行。在异步操作的场合下，没有比发送这个状态码更方便的做法了。 　　返回202状态码的响应的目的是允许服务器接受其他过程的请求（例如某个每天只执行一次的基于批处理的操作），而不必让客户端一直保持与服务器的连接直到批处理操作全部完成。在接受请求处理并返回202状态码的响应应当在返回的实体中包含一些指示处理当前状态的信息，以及指向处理状态监视器或状态预测的指针，以便用户能够估计操作是否已经完成。

3.swagger不仅可以通过界面的形式管理接口，接口测试，还可以通过将swagger导入当前java环境中的方式，将后台开发的接口全部导入到java项目中.添加pom.xml中的依赖，后写swagger的config配置即可.
import io.swagger.models.HttpMethod;
import io.swagger.models.Operation;
import io.swagger.models.Path;
import io.swagger.models.Swagger;
import io.swagger.models.parameters.BodyParameter;
import io.swagger.models.parameters.FormParameter;
import io.swagger.models.parameters.Parameter;
import io.swagger.models.parameters.PathParameter;
import io.swagger.models.parameters.QueryParameter;
import io.swagger.parser.SwaggerParser;
public class Swagger2Case {
private static final Logger logger = LoggerFactory.getLogger(Swagger2Case.class);
private static final String targetUrl = "src/test/resources/api/";
private static SwaggerParser parser = new SwaggerParser();
public swagger2case(){
}

}

4.在postman中将swagger中的所有接口导入，方式如下：

4.1 先进入swagger api界面，按F12键盘，在浏览器中找到右侧network处的地址，如下图:

image.png

4.2、打开postman，点击import，贴入swagger的url即可
将图片中的地址http://xx.XX.XX.XX:12222/v2/api-docs 配置到postman中，即可一键导入所有的接口到postman中.

image.png