使用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

 

猜你喜欢