Java「接口文档」示例

接口概念

官方解释：Java接口是一系列方法的声明，是一些方法特征的集合，一个接口只有方法的特征没有方法的实现，因此这些方法可以在不同的地方被不同的类实现，而这些实现可以具有不同的行为（功能）。

我的解释：接口可以理解为一种特殊的类，里面全部是由全局常量和公共的抽象方法所组成。接口是解决Java无法使用多继承的一种手段，但是接口在实际中更多的作用是制定标准的。或者我们可以直接把接口理解为100%的抽象类，既接口中的方法必须全部是抽象方法。（JDK1.8之前可以这样理解）

接口的特点

就像一个类一样，一个接口也能够拥有方法和属性，但是在接口中声明的方法默认是抽象的。（即只有方法标识符，而没有方法体）。

1.接口指明了一个类必须要做什么和不能做什么，相当于类的蓝图。
2.一个接口就是描述一种能力，比如“运动员”也可以作为一个接口，并且任何实现“运动员”接口的类都必须有能力实现奔跑这个动作（或者implement move()方法），所以接口的作用就是告诉类，你要实现我这种接口代表的功能，你就必须实现某些方法，我才能承认你确实拥有该接口代表的某种能力。
3.如果一个类实现了一个接口中要求的所有的方法，然而没有提供方法体而仅仅只有方法标识，那么这个类一定是一个抽象类。（必须记住：抽象方法只能存在于抽象类或者接口中，但抽象类中却能存在非抽象方法，即有方法体的方法。接口是百分之百的抽象类）
4.一个JAVA库中接口的例子是：Comparator 接口，这个接口代表了“能够进行比较”这种能力，任何类只要实现了这个Comparator接口的话，这个类也具备了“比较”这种能力，那么就可以用来进行排序操作了。

为什么要用接口

1.接口被用来描述一种抽象。
2.因为Java不像C++一样支持多继承，所以Java可以通过实现接口来弥补这个局限。
3.接口也被用来实现解耦。
4.接口被用来实现抽象，而抽象类也被用来实现抽象，为什么一定要用接口呢？接口和抽象类之间又有什么区别呢？原因是抽象类内部可能包含非final的变量，但是在接口中存在的变量一定是final，public,static的。

接口文档规范

0.示例代码
1.接口说明
2.接口地址
3.请求方式
4.请求参数
5.响应参数
6.成功示例
7.异常示例

0.示例代码

@RestController
@RequestMapping(“/user”)
@Validated
public class UserController{
@GetMapping(“/page-list”)
public Result getPageList(UserQueryDTO dto) {
//to do…
}
}

1.接口说明

根据条件获取用户分页列表

2.接口地址

/user/page-list

3.请求方式

GET

4.请求参数

参数名称	         参数类型	         参数说明	          是否必传	     传参示例
page	          Integer	       当前页码，不得小于1	    是	           1
pageSize	      Integer	       每页大小，不得小于1	   是     	       10
name	          String	           用户姓名	            否	         大土

5.响应参数

参数名称	        参数类型	                参数说明	                  参数示例
code	         Integer	            响应编码        	           200
message	          String	            响应消息	                   “ok”
timestamp	      String	            响应时间	      “2021-02-03 12:12:12 122”
data	         Object	                响应实体	       {“total”:66,“rows”:[“id”:1,“name”:“大土”,“age”:21]}
total	          Long	               数据总量	                    66
rows	          List	              每页数据集合   	[“id”:1,“name”:“大土”,“age”:21]
id	              Long	               用户主键	                    1
name	         String	               用户姓名   	               “大土”
age	            Integer	               用户年龄	                   21

6.成功示例

//请求
http://localhost:8080/user/page-list?page=1&pageSize=10

//响应
{
“code”: 200,
“message”: “ok”,
“timestamp”: “2021-02-02 20:38:45 252”,
“data”: {
“total”: 66,
“rows”: [
“id”: 1,
“name”: “大土”,
“age”: 21
]
}
}

7.异常示例

//请求
http://localhost:8080/user/page-list

//响应
{
“code”: 400,
“message”: “parameter can not be null:page”,
“timestamp”: “2021-02-02 20:38:45 252”,
“data”: null
}