springboot与swagger2的集成

桃扇骨 2022-04-02 15:48 242阅读 0赞

[https://www.cnblogs.com/fengli9998/p/7522973.html][https_www.cnblogs.com_fengli9998_p_7522973.html]

1、swagger是什么，这个我觉得凡是一个开发人员就应该知道度娘啊，绝对强大。

简单说下，它的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。

2、springboot与swagger的集成：

第一步：jar包的引入：

![20181227111711496][]

**关于jar包的引入出现了一个问题就是版本的问题，可能需要与你的编辑器或者jdk要匹配吧，试了几个才最终成功导入jar。**

第二步：swagger的配置启动类编写：

要使用swagger要进行一些配置，这个在界面的图上是可以显示的：类似于说明书：在这个类中我们会使用注解来进行启动swagger：

![20181227111711514][]

具体配置如下:

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 </td> 
 <td> <code>package</code>&nbsp;<code>com.springboot.example;</code> &nbsp; &nbsp; &nbsp; &nbsp; <code>//swagger2的配置文件，在项目的启动类的同级文件建立</code> &nbsp; <code>import</code>&nbsp;<code>org.springframework.context.annotation.Bean;</code> <code>import</code>&nbsp;<code>org.springframework.context.annotation.Configuration;</code> <code>import</code>&nbsp;<code>springfox.documentation.builders.ApiInfoBuilder;</code> <code>import</code>&nbsp;<code>springfox.documentation.builders.PathSelectors;</code> <code>import</code>&nbsp;<code>springfox.documentation.builders.RequestHandlerSelectors;</code> <code>import</code>&nbsp;<code>springfox.documentation.service.ApiInfo;</code> <code>import</code>&nbsp;<code>springfox.documentation.service.Contact;</code> <code>import</code>&nbsp;<code>springfox.documentation.spi.DocumentationType;</code> <code>import</code>&nbsp;<code>springfox.documentation.spring.web.plugins.Docket;</code> <code>import</code>&nbsp;<code>springfox.documentation.swagger2.annotations.EnableSwagger2;</code> &nbsp; <code>@Configuration</code> <code>@EnableSwagger2</code> <code>public</code>&nbsp;<code>class</code>&nbsp;<code>Swagger2 { </code> <code>//swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@Bean</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>public</code>&nbsp;<code>Docket createRestApi() { </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>return</code>&nbsp;<code>new</code>&nbsp;<code>Docket(DocumentationType.SWAGGER_2)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.apiInfo(apiInfo())</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.select()</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>//为当前包路径</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.apis(RequestHandlerSelectors.basePackage(</code><code>"com.springboot.example.Controller"</code><code>))</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.paths(PathSelectors.any())</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.build();</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>}</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>//构建 api文档的详细信息函数,注意这里的注解引用的是哪个</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>private</code>&nbsp;<code>ApiInfo apiInfo() { </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>return</code>&nbsp;<code>new</code>&nbsp;<code>ApiInfoBuilder()</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>//页面标题</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.title(</code><code>"Spring Boot 测试使用 Swagger2 构建RESTful API"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>//创建人</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.contact(</code><code>new</code>&nbsp;<code>Contact(</code><code>"MarryFeng"</code><code>,&nbsp;</code><code>"http://www.baidu.com"</code><code>,&nbsp;</code><code>""</code><code>))</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>//版本号</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.version(</code><code>"1.0"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>//描述</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.description(</code><code>"API 描述"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>.build();</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>}</code> &nbsp; &nbsp; <code>}</code> </td> 
 </tr> 
 </tbody> 
</table>

这里的坑是：所使用类的引入文件要注意到底是哪个，之前因为这个出错了，

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 </td> 
 <td> <code>@Configuration</code> <code>@EnableSwagger2</code><code>&lt;br&gt;这两个注解，一个是swagger2的配置，一个是项目启动的时候启动swagger2.&lt;br&gt;具体什么意思看下代码就知道了。</code> </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 </td> 
 <td> <code>//为当前包路径</code> <code>&lt;span style=</code><code>"color: #ff0000"</code><code>&gt;.apis(RequestHandlerSelectors.basePackage(</code><code>"com.springboot.example.Controller"</code><code>))&lt;/span&gt;&lt;br&gt;&lt;span style=</code><code>"color: #ff0000"</code><code>&gt;这个包指的是我们在哪些类中使用swagger2来测试。&lt;/span&gt;</code> </td> 
 </tr> 
 </tbody> 
</table>

第三步：使用swagger来进行模拟测试：

使用swagger2来进行测试接口主要是在哪些类中使用：这里我们依然选择在controller层：

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 </td> 
 <td> <code>package</code>&nbsp;<code>com.springboot.example.Controller;</code> &nbsp; <code>import</code>&nbsp;<code>com.springboot.example.Service.StudentService;</code> <code>import</code>&nbsp;<code>com.springboot.example.entity.Student;</code> <code>import</code>&nbsp;<code>io.swagger.annotations.Api;</code> <code>import</code>&nbsp;<code>io.swagger.annotations.ApiImplicitParam;</code> <code>import</code>&nbsp;<code>io.swagger.annotations.ApiOperation;</code> <code>import</code>&nbsp;<code>org.slf4j.Logger;</code> <code>import</code>&nbsp;<code>org.slf4j.LoggerFactory;</code> <code>import</code>&nbsp;<code>org.springframework.beans.factory.annotation.Autowired;</code> <code>import</code>&nbsp;<code>org.springframework.web.bind.annotation.PathVariable;</code> <code>import</code>&nbsp;<code>org.springframework.web.bind.annotation.RequestMapping;</code> <code>import</code>&nbsp;<code>org.springframework.web.bind.annotation.RequestMethod;</code> <code>import</code>&nbsp;<code>org.springframework.web.bind.annotation.RestController;</code> &nbsp; <code>/**</code> <code>&nbsp;</code><code>* Created by Administrator on 2017/9/13.</code> <code>&nbsp;</code><code>*/</code> <code>@RestController</code> <code>@RequestMapping</code><code>(</code><code>"api"</code><code>)</code> <code>@Api</code><code>(</code><code>"swaggerDemoController相关的api"</code><code>)</code> <code>public</code>&nbsp;<code>class</code>&nbsp;<code>SwaggerDemoController { </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@Autowired</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>private</code>&nbsp;<code>StudentService studentService;</code> &nbsp; <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>private</code>&nbsp;<code>static</code>&nbsp;<code>final</code>&nbsp;<code>Logger logger= LoggerFactory.getLogger(SwaggerDemoController.</code><code>class</code><code>);</code> &nbsp; &nbsp; <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiOperation</code><code>(value =&nbsp;</code><code>"根据id查询学生信息"</code><code>, notes =&nbsp;</code><code>"查询数据库中某个的学生信息"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiImplicitParam</code><code>(name =&nbsp;</code><code>"id"</code><code>, value =&nbsp;</code><code>"学生ID"</code><code>, paramType =&nbsp;</code><code>"path"</code><code>, required =&nbsp;</code><code>true</code><code>, dataType =&nbsp;</code><code>"Integer"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@RequestMapping</code><code>(value =&nbsp;</code><code>"/{id}"</code><code>, method = RequestMethod.GET)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>public</code>&nbsp;<code>Student getStudent(</code><code>@PathVariable</code>&nbsp;<code>int</code>&nbsp;<code>id) { </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>logger.info(</code><code>"开始查询某个学生信息"</code><code>);</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>return</code>&nbsp;<code>studentService.selectStudentById(id);</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>}</code> &nbsp; &nbsp; <code>}</code> </td> 
 </tr> 
 </tbody> 
</table>

![20181227111711731][]

上面这些可以看下具体的注解是什么意思：

这样swagger2与springboot就集成完毕了。

看下最终效果吧：

访问路径：

http://localhost:8080/swagger-ui.html

![20181227111711745][]

![20181227111711764][]

输入id后，我们可以看到查询结果：、

![20181227111711786][]

是不是很方便，我们不用像postman一样来编写入口，swagger2自动完成：

而且实时更新：

![20181227111711802][]

是不是很方便！

至此swagger2与springboot的集成完毕。

[https_www.cnblogs.com_fengli9998_p_7522973.html]: https://www.cnblogs.com/fengli9998/p/7522973.html
[20181227111711496]: /images/20220402/1c16fb16f643421681f1c1be07e3f81f.png
[20181227111711514]: /images/20220402/4138114596024db9aa035c47ed1c4fbb.png
[20181227111711731]: /images/20220402/49c25186e56b485880cf1bea22fe3197.png
[20181227111711745]: /images/20220402/f041fd11205c41a6a16f13c210991c60.png
[20181227111711764]: /images/20220402/9bfc4781ccce48899445fc4a4fb01786.png
[20181227111711786]: /images/20220402/f1828deb07c9473aa895e5e58e0062fd.png
[20181227111711802]: /images/20220402/622984e9459b45d28b288f32a4a12c1e.png