5通过Swagger生成接口文档

通过Swagger生成接口文档

一、作用和简介

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

• Swagger是一个用于生成服务器接口的规范性文档及接口测试的工具（框架）
  • 生成接口文档
  • 对接口进行测试
• Swagger组件
  • Springfox Swagger2 用于扫描接口信息
  • Springfox Swagger UI 用于生成可视化文档

二、使用

2.1 导入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.2 添加注解

@EnableSwagger2

2.3 测试使用

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

2.4 详细配置

@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

2.5 swagger注解

在接口中添加swagger注解，对接口进行说明，让生成的文档更具体

• @Api 类注解， 说明当前控制器类的作用

• @ApiOperation 接口方法注解，说明此接口的作用

  • value

  • notes

• @ApiImplicitParam 接口方法注解，声明参数约束

  @ApiImplicitParam(paramType = "path", name = "id",value = "要删除的图书ID",required = true,dataType = "int")
  

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