我们提供restful接口的时候，api文档是尤为的重要，它承载着对接口的定义，描述等。它还是和api消费方沟通的重要工具。在实际情况中由于接口和文档存放的位置不同，我们很难及时的去维护文档。个人在实际的工作中就遇到过很多接口更新了很久，但是文档却还是老版本的情况，其实在这个时候这份文档就已经失去了它存在的意义。而 swagger 是目前我见过的最好的api文档生成工具，使用起来也很方便，还可以直接调试我们的api。我们今天就来看下 swagger2 与 springboot 的结合。
准备工作
一个springboot项目，可以直接去官网 生成一个demo 。
一个用户类。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
package cn.itweknow.springbootswagger.model;
import java.io.serializable;
/** * @author ganchaoyang * @date 2018/12/19 10:29 * @description */ public class user implements serializable {
private integer id;
private string name;
private string password;
private string email; } |
项目依赖
web service肯定是一个web项目，所以我们这里依赖了 spring-boot-starter-web 包，其他两个包就是和 swagger 相关的包了。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<dependency> <groupid>org.springframework.boot</groupid> <artifactid>spring-boot-starter-web</artifactid> </dependency>
<dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger2</artifactid> <version> 2.9 . 2 </version> </dependency>
<dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger-ui</artifactid> <version> 2.9 . 2 </version> </dependency> |
swagger配置
springfox docket实例为swagger配置提供了便捷的配置方法以及合理的默认配置。我们将通过创建一个docket实例来对swagger进行配置，具体配置如下所示。
|
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 |
@configuration @enableswagger2 public class swaggerconfig extends webmvcconfigurationsupport {
@bean public docket productapi() { return new docket(documentationtype.swagger_2).select() // 扫描的包路径 .apis(requesthandlerselectors.basepackage( "cn.itweknow.springbootswagger.controller" )) // 定义要生成文档的api的url路径规则 .paths(pathselectors.any()) .build() // 设置swagger-ui.html页面上的一些元素信息。 .apiinfo(metadata()); }
private apiinfo metadata() { return new apiinfobuilder() // 标题 .title( "springboot集成swagger2" ) // 描述 .description( "这是一篇博客演示" ) // 文档版本 .version( "1.0.0" ) .license( "apache license version 2.0" ) .licenseurl( "https://www.apache.org/licenses/license-2.0" ) .build(); }
@override protected void addresourcehandlers(resourcehandlerregistry registry) { registry.addresourcehandler( "swagger-ui.html" ) .addresourcelocations( "classpath:/meta-inf/resources/" );
registry.addresourcehandler( "/webjars/**" ) .addresourcelocations( "classpath:/meta-inf/resources/webjars/" ); } } |
上述代码中的addresourcehandlers方法添加了两个资源处理程序，这段代码的主要作用是对swagger ui的支持。
api文档
好了，到这一步，我们已经在一个springboot项目中配置好了swagger。现在，我们就来看一下如何去使用他。首先我们定义了一个 controller 并提供了两个接口：
通过用户id获取用户 用户登录
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
@restcontroller @requestmapping ( "/user" ) @api (description = "用户相关接口" ) public class usercontroller {
/** * 通过id查询用户 * @return */ @requestmapping (value = "/get" , method = requestmethod.get) @apioperation ( "根据id获取用户" ) public user getuserbyid( @apiparam (value = "用户id" ) integer id) { return new user(); }
@requestmapping (value = "/login" , method = requestmethod.post) @apioperation ( "用户登录" ) public user login( @requestbody user user) { return new user(); } } |
相信大家都注意到了，这个 controller 里面多了很多新的注解，比如说 @api , @apioperation 等，下面我们就来一一解释一下。
@api,这个注解是用在controller类上面的，可以对controller做必要的说明。 @apioperation，作用在具体的方法上，其实就是对一个具体的api的描述。 @apiparam，对api参数的描述。到这里，其实我们的swagger就已经可以有效果了，让我们将项目运行起来先看看效果。访问 http://localhost:8080/swagger-ui.html 即可。
model
在上面的图中可以看到在页面的下方有一个models的标签，那么这个是啥呢。其实这个就是我们api中出现的一些对象的文档，我们也可以通过注解来对这些对象中的字段做一些说明，以方便使用者理解。以文章开头提到的 user 类来做一个说明。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
@apimodel ( "用户实体" ) public class user implements serializable {
@apimodelproperty (value = "用户id" ) private integer id;
@apimodelproperty (value = "用户名称" , required = true ) private string name;
@apimodelproperty (value = "密码" , required = true ) private string password;
@apimodelproperty (value = "用户邮箱" ) private string email; } |
我们来看一下 user 类在swagger上是如何展示的：
有一个细节，那就是required = true的字段上面被红星修饰，代表了必填项。
api测试
在 swagger-ui.html 页面上我们可以直接测试api，如下图所示，点击 try it out ，然后填写参数，并点击 execute 即可进行调用。
好了，对于swagger的介绍就到这里了，最后奉上本文的源码地址， 请戳这里 。
以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持。
原文链接：https://www.jianshu.com/p/bc351bdcafc9
查看更多关于SpringBoot集成Swagger2生成接口文档的方法示例的详细内容...