前后端分离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 = "保存按钮（一般指这个页面下的某个功能）-www（如果类头上的接口负责人不是你一定要加上这一栏，如果是你可以去掉）")   或者 @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文档的设置）：
（转发） swagger注释API详细说明_yilishuku的专栏-CSDN博客