12-springboot集成Swagger

Swagger2 的作用：

随项目自动生成强大RESTful API文档，减少工作量；（不需要自己写api文档了）

API文档与代码整合在一起，便于同步更新API文档的说明；

页面测试功能来调试每个RESTful API；

怎么集成？

1、添加相关依赖

<!-- springfox-swagger2 -->

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>2.9.2</version>

        </dependency>

 

        <!-- springfox-swagger-ui -->

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger-ui</artifactId>

            <version>2.9.2</version>

        </dependency>

2、配置文件（暂时不需要在application.properties配置）

3、编写相关代码，可能需要用到一些注解；

@Api("springboot使用swagger测试")
@RestController
public class SwaggerController {

    @ApiOperation(value = "获取用户信息", notes = "根据id来获取用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "id", value = "用户ID",  dataType = "Integer"),
            @ApiImplicitParam(paramType = "path", name = "status", value = "用户状态", dataType = "Integer")
    })
    @ApiResponses({
            @ApiResponse(code = 400, message = "缺少必要的请求参数"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @RequestMapping(value = "/swagger/{id}/{status}",method = RequestMethod.GET)
    public Users getInfo(@PathVariable("id") Integer id, @PathVariable("status") Integer status) {
        Users users = new Users();
        users.setNick("Tom");
        users.setPhone("13922222342");
        users.setPassword("******");
        users.setEmail("cat@163.com");
        users.setAccount("no12");
        return users;
    }
}

 

具体参考课堂上的样例代码；

 

完成后访问：http://localhost:8080/swagger-ui.html 得到API文档

 

Swagger常用注解：

@Api：用在类上，说明该类的作用；

@ApiOperation：用在方法上，说明方法的作用；

@ApiImplicitParams：用在方法上包含一组参数说明；

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面:

paramType：参数放在哪个地方；

header-->请求参数的获取：@RequestHeader；

query-->请求参数的获取：@RequestParam；

Path-->请求参数的获取：@PathVariable （用于restful接口）；

body（不常用）；

form（不常用）；

name： 参数名；

dataType：参数类型；

required：参数是否必须传；

value：参数的意思；

defaultValue：参数的默认值；

@ApiResponses：用于表示一组响应；

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息；

code：数字，例如400；

message：信息，例如 "请求参数不合法"；

response：抛出异常的类；

@ApiModel：描述一个Model的信息；

@ApiModelProperty：描述一个model的属性；

注解可参考官方：https://github.com/swagger-api/swagger-core/wiki/Annotations 

WebJars是将Web前端Javascript和CSS等资源打包成Java的Jar包,这样在Java Web开发中我们可以借助Maven这些依赖库的管理,保证这些Web资源版本唯一性；