SpringBoot利用Swagger2构建Api文档

现在越来越多的项目使用前后端分离，在开发中我们构建RESTful风格Api时候需要提供对应的接口文档，这个工作量也是想当的惊人的，有时候写几个接口文档可能就需要一天的时间。

我们可以利用SpringBoot整合Swagger2来帮我们快速实现接口文档，它可以根据我们写的注释来实现自动生成接口文档。

整合Swagger2

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. 实现Swagger配置

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .pathMapping("/")
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.kenyon.springboot2train.controller"))
                   .paths(PathSelectors.any())
                   .build().apiInfo(new ApiInfoBuilder()
                           .title("springboot利用swagger2构建api文档")
                           .description("springboot利用swagger2构建api文档，详细信息......")
                           .version("1.0")
                           .contact(new Contact("kenyon","https://github.com/kenyonlover/springboot2train","kenyon@gmail.com"))
                           .build());
       }
   }
   

启动项目，在浏览器地址栏输入http://localhost:8080/swagger-ui.html就能访问swagger页面，说明配置生效了。

解释Swagger中的注解

1. @Api 注解可以用来标记当前 Controller 的功能。

2. @ApiOperation 注解用来标记一个方法的作用。

3. @ApiImplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。

4. 如果有多个参数，则需要使用多个 @ApiImplicitParam 注解来描述，多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。

5. 需要注意的是，@ApiImplicitParam 注解中虽然可以指定参数是必填的，但是却不能代替 @RequestParam(required = true) ，前者的必填只是在 Swagger2 框架内必填，抛弃了 Swagger2 ，这个限制就没用了，所以假如开发者需要指定一个参数必填， @RequestParam(required = true) 注解还是不能省略。

6. @ApiModel 标明参数为一个对象

7. @ApiModelProperty 标记对象中一个变量的意义

   示例：

   @RestController
   @Api(tags = "书籍管理接口") // @Api 注解可以用来标记当前 Controller 的功能。
   @RequestMapping("/book")
   public class BookController {
       @Autowired
       private Book book;
   
       @GetMapping("/defBook")
       @ApiOperation("默认书籍")
       public Book getAuthor() {
           return book;
       }
   
       @PostMapping("/addBook")
       @ApiOperation("添加书籍") // @ApiOperation 注解用来标记一个方法的作用。
       @ApiImplicitParams({ //如果有多个参数，则需要使用多个 @ApiImplicitParam 注解来描述，多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。
               @ApiImplicitParam(name = "book", value = "书籍"), //@ApiImplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以使用defaultValue给参数设置默认值，这样在接口测试的时候可以避免手动输入。
               @ApiImplicitParam(name = "author", value = "作者", required = true)
       })
       public String addBook(@ModelAttribute("b") Book book, @ModelAttribute("a") Author author) {
           System.out.println(book);
           System.out.println(author);
           return "添加" + book.getName() + "(" + author.getName() + " 著)成功！";
       }
   }
   

测试

启动项目，访问http://localhost:8080/swagger-ui.html

选中一个接口，点击打开
选择try it out，进行测试

填好对应的参数并点击Execute执行

最后，我们来看看测试结果

SpringBoot整合Swagger2还是比较简单的，用法也比较单一，虽然对代码的侵入性稍大，但是学习成本却又极低，适合使用。