有道无术,术尚可求,有术无道,止于术。
本系列Spring Boot版本2.7.0
前言
现在都是基于前后端分离开发,前后端开发人员之间的协调沟通显得及其重要,例如后端开发好了一个访问接口,如何将该接口的访问路径、参数、响应结果告知前端?
第一个想到的就是写个API 接口文档
呗~ 写个word
文档?其实不然,现在有很多开源的api文档管理工具,比如Eolinker
,后端将接口信息编辑并保存在线文档中,前端就可以查看了。
然而,这种方式存在一个几个弊端,首先是添加麻烦,入参出参很多时,还是需要花点时间,然后就是如果接口变动,又需要去修改文档。
在线接口文档
工具的出现,解决了这些问题,后端只需要按照规则,写好注解或者注释描述当前接口,就可以在线生成接口文档,直接访问,并且可以直接测试,需要更新时,因为是自动生成的,接口变动了,文档自己也会更新。
但是这种方式,也存在弊端,需要引入第三方框架,并且在代码中需要写很多描述信息,所以具有代码侵入性,具体怎么选择,视情况而定。
Swagger 简介
首先Swagger
是一种规范,在2015年更名为OpenAPI
规范,因其英文全称为OpenAPI Specification
,也简称为OAS
,OpenAPI 3.0.0
是 OpenAPI
规范的第一个正式版本。
OAS
定义一个标准的、与具体编程语言无关的RESTful
风格API的规范。简单来说,就是该规范定义了在编写Web API
接口以及描述信息的一套标准,只要按照规定的格式编写,这样就能使用文档生成工具在线生成。
通常我们所说的Swagger
,指的是SmartBear Software
公司开源的遵循OAS
规范的在线api文档
一系列工具,可以在GitHub 中看到所有组件:
常用组件:
- Swagger Editor: 基于浏览器的编辑器,也就是直接在页面上写接口信息,然后可以预览生成的接口文档信息。
- Swagger UI: 在线api文档可视化界面。
-
Swagger Codegen: 代码生成器,可以基于根据
Swagger
定义的RESTful API
可以自动生成服务端和客户端代码。也就是我们只需要写好接口描述信息反向生成代码。 -
Swagger Core:
Open API
规范的Java 实现,将JAVA 代码解析为API接口描述文件(JSON 或者 YML 格式)。
总结:Swagger
就是一个根据代码,生成Open API
规范的描述文件(JSON或YML格式),然后进行api文档生成并可视化的工具。
Spring Boot 集成Swagger
Swagger
本身并不支持Spring Boot
框架直接生成,所以需要借助到第三方工具包,比如springfox
、springdoc
。
springfox
在前几年之前,使用最多的就是springfox
,但在2020 年 7 月 14 日发布了3.0 版本后,该项目貌似已经不再维护,所以该项目大概或许已经狗带~