率先垂范：微服务架构实战之Swagger规范概述

Posted 2021-04-14 DIST上海数慧

随着微服务架构的广泛流行，REST风格受到越来越多的关注，前后端分离依旧在如火如荼的进行着。我们在开发新一代DGP 5.0版本时，前端基于html5，后端基于Dubbo分布式服务框架，实现了前后端的完全解耦。此时，如何有效地管理REST API，从而实现前后端开发人员的高效交互，是技术交叉层面亟待解决的问题。在这种背景下，上海数慧整体引入Swagger进行REST API管理，极大地提高了开发效率与项目产出。

我们遇到的问题

前后端的完全解耦使得前后端交互都是通过REST Service完成，同时后端各个领域系统间也是通过REST Service来通信。

REST本身虽然有统一的规范，然而对于REST API的管理却没有统一规范。

API定义的沟通只能依赖前端和后台开发人员的口头沟通和word文档说明，这里面就会存在很多不确定因素，比如口头沟通的不确定性、文档版本迭代的繁杂性和滞后性，不仅不利于沟通和版本迭代，也为后期的项目维护增加了成本。

解决方案—引入Swagger

如何更优雅且全面的描述我们的RESTful API呢？对API文档管理的规范有很多，综合文档完善程度、社区活跃度、相关配套产品等因素，进行充分的技术预研后，我们决定采用Swagger来进行REST API的管理。

引入Swagger并投入到具体产品中使用后，Swagger的优点得到了充分的展现：减少交流成本、规范接口定义、UI界面支持自定义、即时更新、减少手工维护文档的工作，大大降低了跨地域沟通和最新版本跟踪带来的风险，让各个领域系统更协调高效地合作，也为DGP 5.0后续的升级扩展提供了坚实有力的支持。

技术架构

在前后端分离的情况下，后台应用通过引入Swagger相关配置和规范将REST Service注册成易读且可供调用的一系列服务，Swagger再以可视化的方式将这一系列服务封装为Web服务供前端开发者调用（我们可以通俗的理解为后端开发者将REST Service以一种方便理解和调用的方式通知前端开发者）。

通过引入Swagger，前后端开发工程师从以前的口头or文档对接方式变成了通过swagger ui界面工具对接，很好地避免了原有对接方式的诸多弊端并充分发挥了Swagger 即时更新、减少手工维护文档、接口规范等优点；为产品的持续迭代和传承，保留了完整的接口规范说明，也为具体的开发之间的接口对接和项目交接节省了大量的时间和不必要的麻烦，从而提高了整个产品的开发效率。

End

转载声明

○

无原创标识的文章请按照转载要求编辑，可直接转载，转载后请将转载链接发送给我们；

○