前后端分离api文档规范
api简介
随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,
swagger就是一款让你更好的书写API文档的框架。 --引用 RyuGou的专栏
swagger 使用
这一栏主要是给会使用和会配置swagger的成员提供一套swagger使用规范,如果是新手,本文后面会加入一整套springboot swagger配置和运行说明。
解读一个api无非分成:接口列表、接口名称、协议、参数释义、mock等。
如果我们把项目分成controller、server、dao、entity的话,那swagger主要作用于controller和entity层。
controller层设置:
类头注释 红色的为描述不需要真正用在项目中 @Api(value = "/测试接口(中英文都可以)", description = "为测试环境下的一个demo页面接口(接口描述一般指某个页面)-www(接口负责人)", tags={"测试页面"})
示例:
@Api(value = "/测试接口", description = "为测试环境下的一个demo页面接口-www", tags={"测试页面"})
示图:
视图
方法头注释 红色的为描述不需要真正用在项目中 @ApiOperation(value = "保存按钮(一般指这个页面下的某个功能)-wcy(如果类头上的接口负责人不是你一定要加上这一栏,如果是你可以去掉)") 或者 @ApiOperation(value = "通过id获取信息")
示例:
@ApiOperation(value = "保存按钮-www")
entity实体层注释:
实体类的注解主要是@ApiModelProperty 。
1、如果前端接口不显示当前字段: @ApiModelProperty(hidden = true)
2、如果需要显示: @ApiModelProperty(name = "user_id"(字段名), notes = "用户id"(字段解释), example = "1"(字段的例子), required = true(是否必填true必填,false非必填,如果没有这栏这默认非必填))
示例
@ApiModelProperty(name = "user_id", notes = "用户id", example = "1", required = true)
代码
视图
为了给前端更友好的api文档体验,项目中会创建vo(显示对象)、po(接收对象)
例如
其他:
如何搭建springboot+swagger:
swagger 注解总结(包含非实体api文档的设置):
https://blog.csdn.net/yilishuku/article/details/81199239
- Swagger RESTful API文档规范
- 如何编写基于OpenAPI规范的API文档
- dotnet core webapi +vue 搭建前后端完全分离web架构
- 从壹开始前后端分离【 .NET Core2.0 Api + Vue 2.0 + AOP + 分布式】框架之三 || Swagger的使用 3.1
- 通过配置多个DispatcherServlet解决SpringMVC RESTAPI前后端分离资源访问的问题
- 基于API的前后端分离开发
- 通过Express4构建Restful API服务器 - 结合AngularJS前后端分离开发
- [API]使用Blueprint来高雅的编写接口文档 前后端api文档,移动端api文档
- SOSOAPI前后端分离开发模式下的接口测试
- Swagger RESTful API文档规范
- 快速编写接口api规范文档工具(Markdown)
- 通过配置多个DispatcherServlet解决SpringMVC RESTAPI前后端分离资源访问的问题
- 从壹开始前后端分离【 .NET Core2.0 Api + Vue 2.0 + AOP + 分布式】框架之七 || API项目整体搭建 6.2 轻量级ORM
- Atitit 提升效率 界面gui方面的前后端分离与cbb体系建设 规范与推荐标准
- T 后端规范文档说明 1.0版
- API-Framework 前后端分离
- 前后端分离开发 使用throttle 限制api的访问速率
- 从壹开始前后端分离【 .NET Core2.0 Api + Vue 2.0 + AOP + 分布式】框架之四 || Swagger的使用 3.2
- Atitit 提升效率 界面gui方面的前后端分离与cbb体系建设 规范与推荐标准
- 教你如何前后端完全分离(非api、ajax)