使用Swagger和SpringFox文档化Spring Boot REST API

　　REST API非常重要。它是一个公共接口，其他模块、应用程序或开发人员需要使用它。拥有适当文档的界面以避免混淆并使其始终保持最新是至关重要的。

　　最受欢迎的API文档规范之一是OpenApi，以前称为Swagger。它允许您使用JSON或YAML元数据描述API的属性。它还提供了一个Web UI，它可以将元数据转换为一个很好的HTML文档。此外，通过该UI，您不仅可以浏览有关API端点的信息，还可以将UI用作REST客户端 - 您可以调用任何端点，指定要发送的数据并检查响应。它非常方便。

　　手动编写此类文档并在代码更改时保持更新是不现实的。这就是SpringFox发挥作用的地方。它是Spring Framework的Swagger集成。它可以自动检查您的类，检测控制器，它们的方法，它们使用的模型类以及它们映射到的URL。没有任何手写文档，只需检查应用程序中的类，它就可以生成大量有关API的信息。多么酷啊？最重要的是，每当您进行更改时，它们都会反映在文档中。

　　添加依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
</dependency>

激活Swagger2:

@SpringBootApplication
@EnableSwagger2
public class ProductApplication {

   public static void main(String[] args) {
      SpringApplication.run(ProductApplication.class, args);
   }
}

Rest控制器：

@RestController
public class ProductController {

   @Autowired
   private ProductService productService;

   @ApiOperation(value = "添加商品", nickname = "createProduct", notes = "备注", tags
         = {"商品",})
   @ApiResponses(value = {
         @ApiResponse(code = 201, message = "创建成功！")})
   @PostMapping(value = "/product")
   public void createProduct(@ApiParam(value = "添加商品") @Valid @RequestBody
                             Product body) {
      productService.create(body);

   }

   @PostMapping(value = "/category")
   public void createCategory(@RequestBody
                              Category body) {
      //productService.create(body);

   }
}

				   

createProduct是有详细中文说明，createCategory是默认的，两者显示API有所不同：

注意，Product作为输入参数，需要进行API定义，在Idea中有一个SwaggerGen插件，安装好后，在Product类中右键选择generate，会有generate swagger选项：

这样就会为你的模型对象自动生成swagger注解：

@ApiModel(value = "商品", description = "用于实现商品管理")
@Entity
public class Product {

   @ApiModelProperty(value = "目录")
   @OneToOne
   public Category m_Category;

   @ApiModelProperty(value = "标识")
   @javax.persistence.Id
   private String Id;

   @ApiModelProperty(value = "名称")
   private String name;

				   

启动Spring Boot应用，访问：

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

显示如下：

上面一个“商品”是ProductController的方法createProduct是有详细中文说明，下面一个显示“product-controller”是createCategory方法，虽然这个方法没有任何Swagger2元注释，但是也自动生成了，名称直接为REST控制器名称。

重要的是，填入提交数据，可以类似postman那样对你的REST API进行数据提交，这样前端小伙伴再也不抱怨你的API不能用了：

访问

http://localhost:8080/v2/api-docs

会生成json格式的API说明，能够导入前端mock工具供前端调试编程。

API文档先行还是API编码先行？

#swagger   #API     

Spring Boot