java接口文档怎么写？java接口文档示例

本文关于java接口文档怎么写？java接口文档示例。

一些刚开始写接口文档的服务端同学，很容易按着代码的思路去编写接口文档，这让客户端同学或者是服务对接方技术人员经常吐槽，看不懂接口文档。这篇文章提供一个常规接口文档的编写方法，给大家参考。

推荐使用的是docway 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

一、请求参数

1. 请求方法

• GET

用于获取数据

• POST

用于更新数据，可与PUT互换，语义上PUT支持幂等

• PUT

用于新增数据，可与POST互换，语义上PUT支持幂等

• DELETE

用于删除数据

• 其他

其他的请求方法在一般的接口中很少使用。如：PATCH HEAD OPTIONS

2. URL

url表示了接口的请求路径。路径中可以包含参数，称为地址参数，如**/user/{id}**，其中id作为一个参数。

3. HTTP Header

HTTP Header用于此次请求的基础信息，在接口文档中以K-V方式展示，其中Content-Type则是一个非常必要的header，它描述的请求体的数据类型。

常用的content-type：

• application/x-www-form-urlencoded

请求参数使用“&”符号连接。

• application/json

内容为json格式

• application/xml

内容为xml格式

• multipart/form-data

内容为多个数据组成，有分隔符隔开

4. HTTP Body

描述http body，依赖于body中具体的数据类型。如果body中的数据是对象类型。则需要描述对象中字段的名称、类型、长度、不能为空、默认值、说明。以表格的方式来表达最好。

示例：



二、响应参数

1. 响应 HTTP Body

响应body同请求body一样，需要描述请清除数据的类型。

另外，如果服务会根据不同的http status code 返回不同的数据结构， 也需要针对不同的http status code对内容进行描述。



三、接口说明

说明接口的应用场景，特别的注意点，比如，接口是否幂等、处理是同步方式还是异步方式等。

四、示例

上个示例（重点都用红笔圈出来，记牢了）：



五、接口工具

推荐使用的是http://docway.net（以前叫小幺鸡） 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

接口概念

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

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

接口的特点

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

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

为什么要用接口

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

接口文档规范

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

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	           用户姓名	            否	         大土1234

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	               用户年龄	                   2112345678910

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
}

上述就是小编为大家整理的java接口文档怎么写？java接口文档示例。

国内(北京、上海、广州、深圳、成都、重庆、杭州、西安、武汉、苏州、郑州、南京、天津、长沙、东莞、宁波、佛山、合肥、青岛)eolink软件分析、比较及推荐。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。