Swagger在springboot里的使用

4.1 介绍

Swagger是一个用于生成服务器接口的规范性文档及接口测试的工具（框架）
- 生成接口文档
- 对接口进行测试
Swagger组件

Springfox Swagger2 用于扫描接口信息
Springfox Swagger UI 用于生成可视化文档

4.2 整合

在服务器接口项目中导入Swagger的依赖

<!-- 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>

配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket getDocket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())                     //指定说明书的"封面"信息
                .select()                                   //监控哪些接口
                .apis(RequestHandlerSelectors.basePackage("com.qfedu.bims.controller"))  //指定文档扫描范围
                .paths(PathSelectors.any())                 //指定生成api的路径
                .build();
        return docket;
    }

    public ApiInfo getApiInfo(){
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("图书管理系统接口文档")
                .description("次文档详细描述了****")
                .version("v1.2")
                .contact(new Contact("", "", ""))
                .build();
        return apiInfo;
    }

}

测试：访问生成的接口文档

http://localhost:8080/swagger-ui.html

4.3 swagger注解

@Api 类注解，说明当前控制器类的作用
@ApiOperation 接口方法注解，说明此接口的作用
- value
- notes
@ApiImplicitParam 接口方法注解，声明参数约束

@ApiImplicitParam(paramType = "path", name = "id",value = "要删除的图书ID",required = true,dataType = "int")@ApiImplicitParams 接口方法注解，声明多个参数的约束

@ApiImplicitParams 接口方法注解，声明多个参数的约束
@ApiModel和@ApiModelProperty对参数实体类进行说明

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "Book对象",description = "图书信息")
public class Book {
    @ApiModelProperty(value = "图书ID",dataType = "int", required = true)
    private Integer id;
    @ApiModelProperty(value = "图书名称",dataType = "String", required = true)
    private String name;
    private String author;
    private double price;
    private String descript;

}

@ApiIgnore

@RestController
@RequestMapping("/book")
@CrossOrigin
@Api(tags = "图书信息管理接口")
public class BookController {

    @Resource
    private BookService bookService;

    //id 通过url传递
    //name 通过url参数传递
    //book 通过data传递
    //token  通过header传递
    @RequestMapping(value = "/test/{id}",method = RequestMethod.POST)
    @ApiIgnore
    public ResultVO test(@PathVariable("id") Integer id,
                         @RequestParam("name") String name,
                         @RequestBody Book book,
                         HttpServletRequest request){
        
        //获取header传递的数据
        String token = request.getHeader("token");
        System.out.println(token);
        return new ResultVO(0,"success");
    }
    
    @RequestMapping(value = "/add",method = RequestMethod.POST)
    @ApiOperation(value = "添加图书信息",notes = "调用此接口的注意事项")
    public ResultVO saveBook(@RequestBody Book book)  {
        try {
            bookService.insert(book);
            return new ResultVO<Book>(0,"success",book);
        } catch (Exception e) {
            e.printStackTrace();
            return new ResultVO<Book>(1,"fail",null);
        }
    }

    @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
    @ApiOperation(value = "删除图书信息",notes = "调用此接口的注意事项")
    @ApiImplicitParam(paramType = "path", name = "id",value = "要删除的图书ID",required = true,dataType = "int")
    /**
     * paramType取值: header   query(url?id=123)   path(book/123)
     */
    public ResultVO deleteBook(@PathVariable("id") Integer bookId){
        try {
            bookService.delete(bookId);
            return new ResultVO<Integer>(0,"success",bookId);
        } catch (Exception e) {
            e.printStackTrace();
            return new ResultVO<Book>(1,"fail");
        }
    }

    @RequestMapping(value = "/update",method = RequestMethod.PUT)
    public ResultVO updateBook(@RequestBody Book book)  {
        try {
            bookService.update(book);
            return new ResultVO<Book>(0,"success",book);
        } catch (Exception e) {
            e.printStackTrace();
            return new ResultVO<Book>(1,"fail");
        }
    }

    @RequestMapping(value = "/{id}",method = RequestMethod.GET)
    public ResultVO getBook(@PathVariable("id")Integer bookId){
        try {
            Book book = bookService.getById(bookId);
            return new ResultVO<Book>(0,"success",book);
        } catch (Exception e) {
            e.printStackTrace();
            return new ResultVO<Book>(1,"fail");
        }
    }

    @RequestMapping(value="/list",method = RequestMethod.GET)
    @ApiOperation(value = "查询图书信息列表",notes = "调用此接口的注意事项")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "pageNum",value = "页码",required = true,dataType = "int"),
            @ApiImplicitParam(paramType = "query", name = "pageSize",value = "每页条数",required = true,dataType = "int")
    })
    public ResultVO listBooks(Integer pageNum,Integer pageSize) {
        try {
            List<Book> books = bookService.listBooks(pageNum, pageSize);
            int count = bookService.getCount();
            PageVO<List<Book>> pageVO = new PageVO<List<Book>>(count,books);

            return new ResultVO<PageVO>(0,"success",pageVO);
        } catch (Exception e) {
            e.printStackTrace();
            return new ResultVO<Book>(1,"fail");
        }
    }