前后端分离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

猜你喜欢

转载自blog.csdn.net/yilishuku/article/details/81197448
0条评论
添加一条新回复