RESTful API开发神器swagger与spring-boot的快速整合使用

swagger是一款高效易用的嵌入式文档插件,同时支持在线测试接口，快速生成客户端代码。spring-boot-starter-swagger通过spring-boot方式配置的swagger实现。完美并且完整的支持swagger-spring的所有配置项，配置及其简单，容易上手。支持api分组配置，通过正则表达式方式分组。支持分环境配置，你可以很容易让你的项目api文档在开发环境，测试环境，预发布环境查看，而在生产环境不可查看

快速开始

1.在maven管理的spring-boot项目中引入依赖,（建议使用spring-boot版本1.4以上,1.4以下未测试过）

<dependency>
<groupId>com.gitee.reger</groupId>
<artifactId>spring-boot-starter-swagger</artifactId>
<version>${spring-boot-starter-swagger.version}</version>
</dependency>

2.在spring-boot项目增加配置文件’application-api.yml’,在其中配置swagger的信息，如下

spring:
swagger:
enabled: false                                  # 是否启用swagger
group:
user-api:                                     # 用户组api，可以配置多个组
group-name: 01.user-api                     # api组的名字，会在swagger-ui的api下拉列表中显示；组名前的序号，多个组可以排序；最好不要写中文
title: 用户相关的操作                        # api组的标题，会在swagger-ui的标题处显示
description: 用户相关的操作，包括用户登录登出  # api组的描述，会在swagger-ui的描述中显示
path-regex: /api/user/.*                    # 匹配到本组的api接口，匹配uri，可以用用正则表达式
path-mapping: /                             # 匹配到的url在swagger中测试请求时加的url前缀
version: 0.0.0                              # api版本
license: 该文档仅限公司内部传阅               # 授权协议
license-url: '#'                            # 授权协议地址
terms-of-service-url:                       # 服务条款地址
contact:                                    # 文档联系人
name: 张三                                # 联系人名字
email: zhangsan@team.com                  # 联系人邮箱
url: http://www.team.com                  # 联系地址

以上是swagger的配置，其中组可以配置多个，组名以数字打头，多个组可以排序

3.启用swagger配置

你可以使用

spring.swagger.enabled

设置true来启用配置或者为false禁用配置。

如果没有设置

spring.swagger.enabled

，也可以使用spring-boot的

spring.profiles

包含

api

来启用。

4.配置java代码的文档注解

①. model类中增加配置注解

model中常用的注解：@ApiModel 注解类名，@ApiModelProperty 注解方法或者参数名，

例如

@ApiModel("输出用户数据的类")
public class User implements Serializable {

private static final long serialVersionUID = 1L;
@ApiModelProperty(required=true,value="登录的用户名")
private String userName;
@ApiModelProperty(required=true,value="登录的密码")
private String password;

get/set方法省略，自己脑补吧！
}

②. 控制器中增加配置注解

控制器中常用的注解： @Api 注解控制器显示的标识，有tags和description可以配置控制器显示的标识;@ApiOperation 用来注解控制器方法显示的标识； @ApiParam 用来注解控制器方法参数的名字，控制器方法在文档中需要显示的默认值

例如

@Api(tags = "操作用户的api")
@RestController
@RequestMapping("/api/user")
public class UserController {

@ApiOperation("用户登录")
@GetMapping("/login")
public ResponseEntity<User> login(
@ApiParam("用户名") @RequestParam String userName,
@ApiParam("密码") @RequestParam String password) {
方法体省略，自己脑补吧！
}
}

③.其它一些注解

swagger的注解主要在包‘io.swagger.annotations’下，除了以上描述的注解外，还有@ApiImplicitParam,@ApiImplicitParams,@ApiKeyAuthDefinition,@ApiResponse,@ApiResponses,

@Authorization,@AuthorizationScope,@BasicAuthDefinition,@Contact,@Example,@ExampleProperty,

@Extension,@ExtensionProperty,@ExternalDocs,@Info,@License,@OAuth2Definition,@ResponseHeader,

@Scope,@SecurityDefinition,@SwaggerDefinition,@Tag

除了swagger自己定义的注解外，还有部分校验注解,注解所在包‘javax.validation.constraints’下，像@Max，@Min,@Size这些也是可用的。

由于这些注解，我觉得swagger中可有可无，就不写描述了。

5.查看文档

启动dev环境

java -jar swagger-example.jar --spring.profiles.active=dev --server.port=8080

浏览器访问，http://{服务地址}:8080/swagger-ui.html，如果你启动在本机可以直接点击这里

浏览器便可以展示出swagger的html页面

相关资源

spring-boot-starter-swagger git地址

swagger 官网

spring-boot