简介
Swagger,可用于生成、描述、调用和可视化 RESTful 风格接口的API,是一套规范和完整的开发框架,并且能对接口进行单独测试。
另外, Swagger 在 Github 上面是开源的。
无论对于后端开发,还是前端开发以及测试同事,Swagger 都可以基本满足使用需求。
在 SpringBoot 中集成 Swagger,后端同事写完接口就可以自动生成API文档,可以给到前端同事看,测试同事可以直接测试该接口。
在本篇中,跟大家分享如下内容:
1、在 SpringBoot 中项目如何集成 Swagger?
2、如何使用 Swagger,如何在不同的环境中开启和关闭 Swagger?
3、如何将同类的接口使用 Swagger 注解进行聚合?
更多关于 SpringBoot 的文章,可以点击 微服务项目系列文章 了解,完整代码示例请前往 Github 查看。
集成 Swagger
在 MavenEwpository 搜索 Springfox
,可以找到 Swagger2
和 Swagger UI
,如图所示。
截止到目前, Swagger2
和 Swagger UI
最新版本是 2.9.2
版本。
修改工程的pom文件,增加 Swagger2
和 Swagger UI
的依赖,如下:
1 | <!--swagger--> |
因为我的项目已经集成了 starter-web
,如下 pom 文件中的 dependency:
1 | <dependency> |
这样默认会集成 com.fasterxml.jackson.core:
相关的库,不需要额外再去集成 jackson-databind
了,如下图所示:
否则你需要单独增加 jackson-databind
的依赖,同样的道理你可以在 MavenEwpository 搜索 jackson-databind
选择合适的版本即可。
1 | <dependency> |
工程已经集成了 Swagger
,接下来我们看看如何使用。
使用 Swagger
1、创建Swagger配置
新建一个配置类 MSSwaggerConfig
,该文件名称和位置你可以放到你的工程的任意目录,根据自己的项目目录来放置即可。
MSSwaggerConfig
示例代码如下:
1 |
|
记得添加 @Configuration
、 @EnableSwagger2
这两个注解。
对于 apis(RequestHandlerSelectors.basePackage(pkgName))
目的是只扫描指定包名下面 Controller 的 Swagger 注解,这样就不会去扫描其他包下面的类了。
对于这个配置类,主要是用来生成一些摘要信息,如图:
2、注解 Controller
在 微服务-简单的用户名注册和登录 给大家分享了如何写注册和登录的API,今天还是拿注册的例子来进行 Swagger 的演示。
下面代码是用户注册的示例代码。
1 |
|
可以看到如下的注解:
1 |
这些注解就是 Swagger 的注解,@ApiOperation
说明了该接口的用途,@ApiImplicitParams
中有两个 @ApiImplicitParam
用来对接口的参数进行说明。
如果接口只有一个参数,可以直接使用 @ApiImplicitParam
注解即可。
3、在线文档
配置完成之后,可以启动 SpringBoot 项目,在浏览器中打开下面地址,就可以看到生成的在线文档了。
1 | http://localhost:8080/swagger-ui.html#/ |
点击对应的 Controller 就可以看到对应接口的详细说明了,并且还可以对接口进行测试。
分环境开启 Swagger
在实际项目中,我们一般只会在开发和测试环境使能 Swagger,在沙盒和生成环境会关闭 Swagger,那如何控制呢?
在工程的 Resources
目录下面,新建几个跟环境相关的 properties 文件。
这些文件的命令要满足 application-{profile}.properties
的格式,其中 {profile}
你可以自定义名字,如下我自定义了4个环境,分别是开发、生产、沙盒和测试环境。
我们知道,在 application-{profile}.properties
中配置的选项与在 application.properties
中配置的选项如果名称相同,优先会使用 application-{profile}.properties
中配置。
在 application.properties
中配置如下:
1 | # 配置使用哪个环境 |
对应的在 application-dev.properties
和 application-test.properties
中开启 swagger,如下:
1 | # 启用 swagger |
选项配置完成后,我们在代码中使用该选项,修改 MSSwaggerConfig
如下(只列出了修改部分的关键代码):
1 |
|
在下面的代码中读取配置
1 |
|
然后调用 Docket 的 enable(enableSwagger)
方法来决定是否开启 Swagger,如果配置不开启,效果图如下:
还有其他方式来控制在不同环境下配置 Swagger 是否开启,比如可以结合注解 @Profile
通过不同的 profile 给 Swagger 的依赖设置不同的 scope,还可以使用注解 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
,大家自行选择适合自己项目的方案即可,目的都是一样。
聚合接口
在上面实例中,我们可以看到登录和注册都属于用户模块,使用注解 @API
可以聚合显示这些接口。
在登录和注册的 Controller 中可以添加下面注解,从而来聚合显示接口。
1 |
注册 Controller 添加注解,如下:
1 |
|
登录 Controller 添加注解,如下:
1 | @Api(value="signin", tags="用户模块") |
显示效果如下:
你眼睛看到的不一定是事实的全部~