Swagger2
1 Swagger2
1.1 Swagger2简介
Swagger2–自动生成接口文档
优点:
- 代码变,文档变。只需要少量的注解,Swagger 就可以根据代码自动生成 API 文档,很好的保证了文档的时效性。
- 跨语言性,支持 40 多种语言。
- Swagger UI 呈现出来的是一份可交互式的 API 文档,我们可以直接在文档页面尝试 API 的调用,省去了准备复杂的调用参数的过程。
- 还可以将文档规范导入相关的工具(例如 Postman、SoapUI), 这些工具将会为我们自动地创建自动化测试。 Swagger是一套围绕Open API 规范构建的开源工具,可以帮助设计,构建,记录和使用REST API。
1.1 Swagger2引入
前后端分离:
- 后端:后端控制层,服务层,数据访问层【后端团队】
- 前端:前端控制层,视图层【前端团队】
- 伪造后端数据 Json,不需要后端,程序依旧能运行
- 前后端如何交互?===> API
- 前后端相对独立,松耦合
- 前后端甚至可以部署在不同的服务器上
- 后端提供接口,需要实时更新最新的消息及改动!
前后端分离产生一个问题:
- 前后端继承联调,前端人员和后端人员无法做到,及时协商,尽早解决。最终导致问题集中爆发!
解决方案:
- 指定一个schema (计划或理论的提要,纲要)实时更新最新的API,降低集成的风险
- 早些年:制定world计划文档。
- 前后端分离:
- 前端测试后端接口:postman - 后端提供接口,需要实时更新到最新的消息及改动。
接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新,导致前端人员抱怨接口文档和实际情况不一致。
很多程序员会抱怨别人写的接口文档不规范,不及时更新。但自己写的时候也觉得烦——太痛苦了。如果接口文档可以实时动态生成就不会出现上面问题。
Swagger可以完美解决上面的问题。
1.2 Swagger 工具包括的组件
Swagger 工具包括的组件:
- Swagger Editor:基于浏览器编辑器,可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。(用的比较少,自定义配置时才用)
- Swagger UI: 将Open API 规范呈现为交互式API文档。用可视化 UI展示描述文件。(通过浏览器,根据代码中的 注解 查看)
- Swagger Codegen:将OpenAPI 规范成为服务器存根(可以生成文件,方便访问服务器信息,快速展示)和客户端库。通过Swagger Codegen 可以将描述文件生成html格式和cwiki形式的文档接口,同时也可以生成多种言语的客户端和服务段代码。
- Swagger Inspector:和Swagger UI有点类似,但是可以返回更多信息(多了过程记录),也会保存请求时及参数数据。
- Swagger Hub:继集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub 中可以帮助完成上面项目的所有工作,需要注册账号,分免费版和收费版。
使用Swagger,就是把相关信息存储在它定义的描述文件里面(
yml
和
json
格式),再通过维护整个描述文件可以去更新接口文档,以及生成各端代码。
- Swagger号称世界上最流行的Api框架
- 通过Swagger给一些比较难理解的属性或者接口添加注释信息
- Rest Api 文档在线自动生成工具 -> Api文档与Api定义实时更新
- 直接运行,可以在线测试API接口
- 支撑多种语言:(Java,PHP…)
2 Spring整合使用Swagger2
2.1 导入依赖
<!-- swagger依赖 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!-- swagger ui依赖 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>
2.2 Swagger2Config配置类
@Configuration@EnableSwagger2publicclassSwagger2Config{@BeanpublicDocketgetDocket(){//创建Docket对象Docket docket =newDocket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())//指定API接口文件首页信息.select()//初始化并返回一个API选择构造器.apis(RequestHandlerSelectors.any())//为任何接口生成API文档.paths(PathSelectors.any())//可以根据url路径设置哪些请求加入文档,忽略哪些请求.build();//创建API文档return docket;}privateApiInfogetApiInfo(){//创建作者 对象Contact contact =newContact("尼古拉斯","http://www.baidu.com","[email protected]");ApiInfo apiInfo =newApiInfoBuilder().title("《麦淘乐后端接口文档》")//文档标题.description("文档的描述信息...")//文档描述.contact(contact)//文档作者.version("V1.0")//文档版本.build();//构建return apiInfo;}}
2.3 测试
启动SpringBoot项目访问:http://localhost:8888/swagger-ui.html
3 Swagger2常用注解
3.1 Controller注解
@Api
:修饰整个类,描述Controller的作用 - tags:“说明该类的作用”
@RestController@RequestMapping("users")@Api(tags ="用户管理API")publicclassUserController{//TODO}
3.2 方法注解
@ApiOperation
:描述一个类的一个方法(一个接口) - value=“说明方法的作用”- notes=“方法的备注说明”@ApiImplicitParams
:描述由多个@ApiImplicitParam
注解的参数组成的请求参数列表@ApiImplicitParam
:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值 - name:参数名- value:参数的汉字说明、解释- required:参数是否必须传- dataType :参数类型,默认String,其它值dataType=“int”- defaultValue:参数的默认值- paramType:参数放在哪个地方 - header --> 请求参数的获取:@RequestHeader- query --> 请求参数的获取:@RequestParam- path(用于restful接口)–> 请求参数的获取:@PathVariable- body(请求体)–> @RequestBody User user- form(普通表单提交)
@ApiOperation(value="用户登录",notes="备注:手机号码唯一")@ApiImplicitParams({@ApiImplicitParam(name="mobile",value="手机号",required=true),@ApiImplicitParam(name="password",value="密码",required=true)})@PostMapping("/login")publicResultVOlogin(@RequestParamString mobile,@RequestParamString password){//TODO}
3.3 实体类注解
@ApiModel
:用对象来接收参数时,用于描述对象(实体类中的注解) - (这种一般用在post创建的时候,使用 @RequestBody 这样的场景,请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )@ApiProperty
:用对象接收参数时,描述对象的一个字段(实体类中属性的注解)
@Data@NoArgsConstructor@AllArgsConstructor@ApiModelProperty(value ="用户ID",example ="1")privateInteger id;@ApiModelProperty(value ="登录账户",example ="1")privateString username;@ApiModelProperty(value ="账户密码",example ="1")privateString password;}
3.4 方法返回值注解
@ApiResponses
:方法返回对象的说明 -@ApiResponse
:每个参数的说明 - code:数字,例如400- message:信息,例如"请求参数没填好"
@ApiResponses({@ApiResponse(code =200,message ="请求成功"),@ApiResponse(code =201,message ="请求失败,参数错误"),@ApiResponse(code =202,message ="请求失败,未知错误")})
3.5 忽略方法
@ApiIgnore
:接口方法注解,添加此注解的方法将不会生成到接口文档中
3.6 swagger-ui插件
导入依赖
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version></dependency>
3.7拦截器放行swagger2资源
.excludePathPatterns("/swagger-ui.html","/webjars/**","/swagger-resources/**","/v2/**");
版权归原作者 凌晨五点深蓝 所有, 如有侵权,请联系我们删除。