Swagger 产品介绍

2021-09-18 0 By admin

在前后端分离开发中,为了减少与其他团队的沟通成本,一般构建一份 Restful API 文档来描述所有的接口信息,但是这种做法有很大的弊端:

  • 接口众多,编写 Restful API 文档工作量巨大;接口文档中细节点很多,如:基本信息、接口地址、入参、返回值;请求类型、消息头、认证信息等。
  • 维护不方便,每次接口发生变化,都需要修改文档。
  • 接口测试不方便,一般需要借助第三方工具(如Postman)测试。

Swagger2 是一个开源软件框架,可以帮助开发人员设计、构建、记录和使用 Restful Web 服务,它将代码和文档融为一体,可以完美解决上面的问题,使开发人员专注于开发工作。

一、OpenAPI Specification

OpenAPI 规范(OAS)为 RESTful API 定义了一套标准的、跨语言的接口,以便人类和计算机均无需通过源码、文档或网络流量检测探知和理解服务器提供的能力。
OAS 可用于制作文档生成器、代码生成器、测试工具等等。OpenAPI 以 json 对象形式呈现,因此它基本遵循 json schema 规范,可以用 json 或 yaml 格式编写。

1.1、OpenAPI 文档的基础数据包含

  1. openapi: OAS 版本号,影响解析策略。
  2. info: RESTful API 的元信息,包含标题、描述、联系方式、许可证、版本号、服务条款链接。
  3. servers: 服务器信息。当 servers 未指定时,将使用 url 为 ‘/’ 的服务器对象。
  4. paths: RESTful API 的路径。单个路径包含相同配置时会造成冲突,这时会由工具决定选用哪一个。路径下挂操作对象。
  5. components: 在 OAS 中作为可重用的部件,被引用时才生效。
  6. security: RESTful API 的安全机制,可以在操作对象层级进行改写。
  7. tags: 标签列表,即针对操作对象打标签。
  8. externalDocs: 扩展文档。

1.2、OAS 与 Swagger 的关系

Swagger 遵循了 OpenAPI 规范,OpenAPI 是 Linux 基金会的一个项目,试图通过定义一种用来描述 API 格式或 API 定义的语言,来规范 RESTful 服务开发过程。
Swagger 可以看作是一个遵循了 OpenAPI 规范的一项技术,而 springfox 则是这项技术的具体实现。 就好比 Spring 中的 AOP 和 DI 一样,前者是思想,而后者是实现。

二、Swagger 介绍

Swagger 3.0 发布已经有一段时间了,它于 2020.7 月 发布;但目前市面上使用的主流版本还是 Swagger 2.X 版本和少量的 1.X 版本。
在 OpenAPI 规范的基础上,Swagger 提供了一套开源工具用于为服务端和客户端设计、制作 api 文档以及代码,包含 Swagger Editor、Swagger UI、Swagger Codegen。

2.1、Swagger Codegen

通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档,同时也能生成多钟语言的服务端和客户端的代码。
支持通过jar包,docker,node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

2.2、Swagger UI

提供了一个可视化的UI页面展示描述文件。
接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

2.3、Swagger Editor

类似于markendown编辑器的编辑Swagger描述文件的编辑器,该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

2.4、Swagger Inspector

感觉和postman差不多,是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求,会返回更多的信息,也会保存你请求的实际请求参数等数据。

2.5、Swagger Hub

集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。

三、总结

3.1、开发流程

基于 Swagger,开发流程可能是这样的:

  1. 设计 api,使用 Swagger Codegen 制作服务端代码,稍后再实现业务逻辑
  2. 使用 Swagger Codegen 生成客户端脚本库
  3. 使用 Swagger UI 制作交互式文档界面等等

3.2、Spring Swagger整合

Spring 基于 swagger 规范,可以将基于 SpringMVC 和Spring Boot项目的项目代码,自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的。