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: [e-mail]                  # 联系人邮箱          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