五分钟教你上手swagger

一，swagger是什么？

swagger是一种基于Rest样式的api文档开发工具，我们常常替换前替换项目，解决由于前直接分离导致的数据接口替代问题，有效减少前端程序员与编程程序员的打斗次数。

swagger自己是这样介绍swagger的：

1、Swagger是一组功能强大且易于使用的API开发人员工具套件，适用于团队和个人，可在整个API生命周期（从设计和文档到测试和部署）中进行开发。

2、Swagger由开放源代码，免费和市售工具共同组成，它使任何人（从技术工程师到街头智能产品经理）都可以配置每个人都喜欢的惊人的API。 3、Swagger由SmartBear Software合并，并成为团队软件质量工具的领导者。SmartBear在此软件领域的一些知名企业，包括Swagger，SoapUI和QAComplete。

二，使用

1，日期依赖

在pom.xml文件中加入依赖

2，配置

主要从这几个方面来配置swagger

1，配置swagger配置 2，配置swagger扫描 3，配置swagger2设置分组 4，实体类设置

2.1，配置swagger配置

首先若要使用swagger需要在配置文件上加上@EnableSwagger2注解，使用swagger2执行。

以下就是最简单的配置方法

如果你不知道ApiInfo的插入含义，我们可以查看他的构造方法，里面分别是它所代表的含义，这个相信会一点英文的都能够看得懂。

而ApiInfo并没有自己属性的set方法，所以我们只能使用构造方法来进行注入。

此时无需配置其他的我们也可以直接使用swagger。

：http：// localhost：8080 / swagger-ui.html。

在我的项目里一共有三个控制器：LoginController、RegisterController、OssController

其中1，红色框内就是我配置的一些信息，而标注的①②③是我自己的controller，额外的④是替代的controller，也就是我们访问出错的/error页面

2.2，配置swagger扫描

若我们在开发中不想看到任何的控制器或需要隐藏其他的控制器，我们可以使用以下配置

其中，apis参数中RequestHandlerSelectors一共有五种配置：

而.paths（PathSelectors.ant（“ / admin / **”）），指的是我只扫描/admin/路径下的所有请求。

2.3，配置swagger2设置分组

当我们在实际的开发中，一个项目经常由多个开发人员共同协作完成的，而swagger恰好可以在这方面解决这一问题。

我们再在原来的基础上加上两个Docket，当然实际中我们需要配置的往往不会这么简单，这里只是举例说明。

可以看到，在原来的分组中多了两个组，这样我们的程序员就可以只看自己的负责的接口了。

2.4，实体类设置

我们可以在实体类中对我们的模型对象进行一些说明。@ApiModel对实体类的说明， @ApiModelProperty对类的属性的说明。

另外： swagger的常用API

1. api标记Api用在类上，说明该类的作用。可以标记一个控制器类作为swagger文档资源，使用方式：

1. ApiOperation标记ApiOperation：用在方法上，说明方法的作用，每一个网址资源的定义，使用方式：

1. ApiParam标记ApiParam请求属性，使用方式：

1. ApiResponse ApiResponse：响应配置，使用方式：@ApiResponse（代码= 400，消息=“提供了无效的用户”）

1. ApiResponses ApiResponses：响应集配置，使用方式：@ApiResponses（{@ ApiResponse（code = 400，message =“ Invalid Order”）}）

1. ResponseHeader响应头设置，使用方法@ResponseHeader（name =“ head1”，description =“ response head conf”）

例如：我在我的上传文件的控制器上加上注解说明

这样就可以对我们的接口进行中文说明。

2.5，接口测试

swagger还为程序员提供了接口的测试功能，例如：测试登录接口，填上需要的信息，单击下方的Try it out进行测试。

从显示的数据中可以清晰地到看到我们所需要的信息：请求地址，请求头，请求体，状态码，响应头信息。

三，拓展

这里有这样一个问题，也常常会作为面试题出现：

答：建立需要好几个springboot配置文件，例如application.yml， ，application-pro.yml，，application-dev.yml分别用于默认，部署后，的开发环境中在application.yml指定当前使用的的英文哪一个

然后，再在swagger配置中配置，如果当前环境使用的是dev的配置文件，就是用enable(flag)，来关闭swagger功能。

这样就能使项目上线后不暴露接口，有效的提高安全性。

总的来说，swagger是一个很好用的api文档工具，并且上手难度不高，最关键的是能减少前程序员程序员的打斗次数，你值得拥有。

1，swagger介绍及两种使用方法[1]

参考文献

[1]1，swagger介绍及两种使用方法：https ://blog.csdn.net/weixin_37509652/article/details/80094370