Swagger ,可用于生成、描述、调用和可视化 RESTful 风格接口的API,是一套规范和完整的开发框架,并且能对接口进行单独测试。
另外, Swagger 在 Github 上面是开源的。
无论对于后端开发,还是前端开发以及测试同事,Swagger 都可以基本满足使用需求。
在 SpringBoot 中集成 Swagger,后端同事写完接口就可以自动生成API文档,可以给到前端同事看,测试同事可以直接测试该接口。
在本篇中,跟大家分享如下内容:
1、在 SpringBoot 中项目如何集成 Swagger?
2、如何使用 Swagger,如何在不同的环境中开启和关闭 Swagger?
3、如何将同类的接口使用 Swagger 注解进行聚合?
更多关于 SpringBoot 的文章,可以点击微服务项目系列文章 了解,完整代码示例请前往 Github 查看。
在 MavenEwpository 搜索 Springfox
,可以找到 Swagger2
和 Swagger UI
,如图所示。
截止到目前, Swagger2
和 Swagger UI
最新版本是 2.9.2
版本。
修改工程的pom文件,增加 Swagger2
和 Swagger UI
的依赖,如下:
<!--swagger--> <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>
因为我的项目已经集成了 starter-web
,如下 pom 文件中的 dependency:
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
这样默认会集成 com.fasterxml.jackson.core:
相关的库,不需要额外再去集成 jackson-databind
了,如下图所示:
否则你需要单独增加 jackson-databind
的依赖,同样的道理你可以在 MavenEwpository 搜索 jackson-databind
选择合适的版本即可。
<dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.9.8</version> </dependency>
工程已经集成了 Swagger
,接下来我们看看如何使用。
新建一个配置类 MSSwaggerConfig
,该文件名称和位置你可以放到你的工程的任意目录,根据自己的项目目录来放置即可。
MSSwaggerConfig
示例代码如下:
@Configuration @EnableSwagger2 public class MSSwaggerConfig{ @Bean public Docket msblogDocket(){ Docket docket = new Docket(DocumentationType.SWAGGER_2); String pkgName = "com.veryitman.springboot.controller"; return docket.apiInfo(msblogAPIInfo()).select() .apis(RequestHandlerSelectors.basePackage(pkgName)) .paths(PathSelectors.any()) .build(); } private ApiInfo msblogAPIInfo(){ ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder(); String apiTitle = "MSBlog Server API"; String apiDes = "API for MSBlog"; String apiVersion = "1.0.0"; String homePage = "http://veryitman.com"; String emailUrl = "veryitman@126.com"; Contact contact = new Contact("itman", homePage, emailUrl); return apiInfoBuilder.title(apiTitle).description(apiDes) .version(apiVersion) .contact(contact) .license("Apache 2.0") .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html") .build(); } }
记得添加 @Configuration
、 @EnableSwagger2
这两个注解。
对于 apis(RequestHandlerSelectors.basePackage(pkgName))
目的是只扫描指定包名下面 Controller 的 Swagger 注解,这样就不会去扫描其他包下面的类了。
对于这个配置类,主要是用来生成一些摘要信息,如图:
在 微服务-简单的用户名注册和登录 给大家分享了如何写注册和登录的API,今天还是拿注册的例子来进行 Swagger 的演示。
下面代码是用户注册的示例代码。
@RestController @RequestMapping(value = "signup") public class MSSignupController{ @CrossOrigin(origins = {"*"}) @PostMapping(value = "/name") @ApiOperation(value = "用户注册", httpMethod = "POST", notes = "用户名和密码注册") @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "注册的用户名", required = true), @ApiImplicitParam(name = "userpwd", value = "注册的密码", required = true) }) public MSResponse signup(@RequestParam(value ="username")String userName, @RequestParam(value ="userpwd")String userPwd){ // 省略 } }
可以看到如下的注解:
@ApiOperation(value = "用户注册", httpMethod = "POST", notes = "用户名和密码注册") @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "注册的用户名", required = true), @ApiImplicitParam(name = "userpwd", value = "注册的密码", required = true) })
这些注解就是 Swagger 的注解, @ApiOperation
说明了该接口的用途, @ApiImplicitParams
中有两个 @ApiImplicitParam
用来对接口的参数进行说明。
如果接口只有一个参数,可以直接使用 @ApiImplicitParam
注解即可。
配置完成之后,可以启动 SpringBoot 项目,在浏览器中打开下面地址,就可以看到生成的在线文档了。
http://localhost:8080/swagger-ui.html#/
点击对应的 Controller 就可以看到对应接口的详细说明了,并且还可以对接口进行测试。
在实际项目中,我们一般只会在开发和测试环境使能 Swagger,在沙盒和生成环境会关闭 Swagger,那如何控制呢?
在工程的 Resources
目录下面,新建几个跟环境相关的 properties 文件。
这些文件的命令要满足 application-{profile}.properties
的格式,其中 {profile}
你可以自定义名字,如下我自定义了4个环境,分别是开发、生产、沙盒和测试环境。
我们知道,在 application-{profile}.properties
中配置的选项与在 application.properties
中配置的选项如果名称相同,优先会使用 application-{profile}.properties
中配置。
在 application.properties
中配置如下:
# 配置使用哪个环境 spring.profiles.active=dev # 默认不启用 swagger swagger.enable=false
对应的在 application-dev.properties
和 application-test.properties
中开启 swagger,如下:
# 启用 swagger swagger.enable=true
选项配置完成后,我们在代码中使用该选项,修改 MSSwaggerConfig
如下(只列出了修改部分的关键代码):
@Configuration @EnableSwagger2 public class MSSwaggerConfig{ @Value("${swagger.enable}") private boolean enableSwagger; @Bean public Docket msblogDocket(){ Docket docket = new Docket(DocumentationType.SWAGGER_2).enable(enableSwagger); String pkgName = "com.veryitman.springboot.controller"; return docket.apiInfo(msblogAPIInfo()) .select() // 只扫描指定包名下面的Controller中的Swagger注解 .apis(RequestHandlerSelectors.basePackage(pkgName)) .paths(PathSelectors.any()) .build(); }
在下面的代码中读取配置
@Value("${swagger.enable}") private boolean enableSwagger;
然后调用 Docket 的 enable(enableSwagger)
方法来决定是否开启 Swagger,如果配置不开启,效果图如下:
还有其他方式来控制在不同环境下配置 Swagger 是否开启,比如可以结合注解 @Profile
通过不同的 profile 给 Swagger 的依赖设置不同的 scope,还可以使用注解 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
,大家自行选择适合自己项目的方案即可,目的都是一样。
在上面实例中,我们可以看到登录和注册都属于用户模块,使用注解 @API
可以聚合显示这些接口。
在登录和注册的 Controller 中可以添加下面注解,从而来聚合显示接口。
@Api(value="xxx", tags="用户模块")
注册 Controller 添加注解,如下:
@Api(value="signup", tags="用户模块") @RestController @RequestMapping(value = "signup") public class MSSignupController{ }
登录 Controller 添加注解,如下:
@Api(value="signin", tags="用户模块") @RestController @RequestMapping(value = "signin") public class MSSigninController { }
显示效果如下: