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");
          }
      }