swagger2：两分钟学会swagger

学习背景

或许我们习惯用postman调试接口，但是你会发现，每次调试一个接口时都需要把路径和参数写上去，有的时候还容易写错，大大耽误了咱们的开发时间。

swagger是什么东西？

swagger用于定义API文档。

优点

• 前后端分离开发
• API文档非常明确
• 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
  传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件）
• spring-boot与swagger的集成简单的一b

实践

• 项目前准备一个maven+spring boot项目（自己去ij IDE上自动生成一个）

第一步：

在maven 中加入下面俩个依赖，一定是2.6.1之后的，之前的我试过几个不能用：

    
        io.springfox
        springfox-swagger2
        2.6.1
        compile
    

---

    
        io.springfox
        springfox-swagger-ui
        2.6.1
        compile
    

第二步：

写一个配置类：

@EnableSwagger2
@Configuration
class Swagger2 {
@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()  //RequestHandlerSelectors.any()，所有的路劲都去扫描
            //这个扫描包的意思一样，固定路劲就去相应的路劲扫描
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.talkCloud.controller"))
            .paths(PathSelectors.any())
            .build();
}

//就是对生成的api文档的一个描述
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("文档标题")
            .description("文档描述")
            .termsOfServiceUrl("相关url")
            .contact("名字-UP主")
            .version("版本：1.0")
            .build();
    }
 }

【注意】：实现这两步就能完成文档的生成了，可以尝试用localhost:8080/swagger-ui.html 访问，端口是spring boot 启动时设置的，自己看。

第三步：

去你的controller层用注解标记Controller，常用的注解我写在下面了，这些注解都是为了丰富api文档诞生的。这里先举个例如：

@ApiImplicitParams({
        @ApiImplicitParam(name = "Authorization", value = "Authorization token",
                required = true, dataType = "string", paramType = "header"),
        @ApiImplicitParam(name = "studentId", value = "学生id", dataType = "Long", paramType = "query"),
        @ApiImplicitParam(name = "subjectId", value = "科目id", dataType = "Integer", paramType = "query"),
        @ApiImplicitParam(name = "pageSize", value = "页大小", dataType = "Integer", paramType = "query"),
        @ApiImplicitParam(name = "pageNo", value = "第几页", dataType = "Integer", paramType = "query"),
})
@ApiOperation(value = "学生课程表获取", httpMethod = "GET", response = ResponseEntity.class)
@RequestMapping(value = "student/course/table", method = RequestMethod.GET)
public ResponseEntity saveResourceSec(
        @RequestParam(name = "studentId") Long studentId,
        @RequestParam(name = "subjectId", required = false) Integer subjectId,
        @RequestParam(value = "pageSize", defaultValue = "25") Integer pageSize,
        @RequestParam(value = "pageNo", defaultValue = "1") Integer pageNo,
        @RequestParam(value = "modifiedOn", required = false) Date modifiedOn

) {
    PageWrapper result = studentCourseTableService.getStudentCourseById(studentId, subjectId, pageNo, pageSize, modifiedOn);

    return ResponseEntity.ok(result);
}

【常见注解解读】

其实自己领悟一下就好，就按照单词表名意思，简单！

• @Api：用在类上，说明该类的作用
• @ApiOperation：用在方法上，说明方法的作用
• @ApiImplicitParams：用在方法上包含一组参数说明
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  • paramType：
    • header-->请求参数的获取：@RequestHeader
    • query-->请求参数的获取：@RequestParam
    • path（用于restful接口）-->请求参数的获取@PathVariable
    • cookie：which are passed in the Cookie header, such as Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU
    • body（不常用）
    • form（不常用）
  • name：参数名
  • value：对参数的描述
  • dataType：参数类型
  • required：参数是否必须传
  • defaultValue：参数的默认值
• @ApiResponses：用于表示一组响应
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  • code：数字，例如400
  • message：信息，例如"请求参数没填好"
  • response：抛出异常的类