使用Swagger和SpringFox文档化SpringBootRESTAPI

微信扫一扫,分享到朋友圈

使用Swagger和SpringFox文档化SpringBootRESTAPI

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

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

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

添加依赖:

    io.springfox
    springfox-swagger2
    2.6.1
    compile


    io.springfox
    springfox-swagger-ui
    2.6.1
    compile

激活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

微信扫一扫,分享到朋友圈

使用Swagger和SpringFox文档化SpringBootRESTAPI

minikube [FATAL] plugin/loop: Seen “HINFO IN xxx.” more than twice, loop detected

上一篇

论前泽友作绕月旅行 有钱真能为所欲为!

下一篇

你也可能喜欢

使用Swagger和SpringFox文档化SpringBootRESTAPI

长按储存图像,分享给朋友