java http调用接口书写？

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

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

一、请求参数

1 请求方法

GET

用于获取数据

POST

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

PUT

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

DELETE

用于删除数据

其他

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

2 URL

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

3 >

>

常用的content-type：

application/x->

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

application/json

内容为json格式

application/xml

内容为xml格式

multipart/form-data

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

4 >

描述>

示例：

二、响应参数

1 响应 >

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

另外，如果服务会根据不同的>

三、接口说明

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

四、示例

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

五、接口工具

推荐使用的是>1、引入包(本文中的包全部引自struts-2181\lib)：
struts2-json-plugin-2181jar
json-lib-21jar
commons-collections-32jar
commons-beanutils-170jar
commons-lang-23jar
commons-logging-104jar
ezmorph-103jar
这7个包是返回json形式的数据必须的。因为json大量引用了Apache commons的包，所以要加入4个，commons包，除了commons的包外，还需要引入一个 ezmorph的包。最后加入struts2必须的6个包：
struts2-core-2181jar
xwork-core-216jar
ognl-273jar
freemarker-2315jar
commons-fileupload-121jar
commons-io-132jar
2、后台：
1) Userinfo实体类代码
public class UserInfo implements Serializable {
private int userId;
private String userName;
private String password;
get set方法略
}
2) Action类
public class TestAction extends ActionSupport {
private String message; //使用json返回单个值
private UserInfo userInfo; //使用json返回对象
private List userInfosList; //使用josn返回List对象
get set方法略
/返回单个值/
public String returnMsg(){
thismessage = "成功返回单个值";
return SUCCESS;
}
/返回UserInfo对象/
public String returnUser(){
userInfo = new UserInfo();
userInfosetUserId(10000);
userInfosetUserName("刘栋");
userInfosetPassword("123456");
return SUCCESS;
}
/返回List对象/
public String returnList(){
userInfosList = new ArrayList<UserInfo>();
UserInfo u1 = new UserInfo();
u1setUserId(10000);
u1setUserName("张三");
u1setPassword("111111");
UserInfo u2 = new UserInfo();
u2setUserId(10001);
u2setUserName("李四");
u2setPassword("222222");
userInfosListadd(u1);
userInfosListadd(u2);
return SUCCESS;
}
}
3) strutsxml（必须继承json-default、json-default继承自struts-default）
<package name="default" namespace="/json" extends="json-default">
<action name="returnMsg" class="comtestAction " method="returnMsg">
<result name="success" type="json">
<param name="root">validate</param>
</result>
</action>
<action name="returnUser "
class="comtestAction " method="returnUser ">
<result name="success" type="json">
<param name="includeProperties">
userInfo\userId,userInfo\userName,userInfo\password
</param>
</result>
</action>
<action name="returnList" class="comtestAction "
method="returnList">
<result name="success" type="json">
<param name="includeProperties">
userInfosList\[\d+\]\userName,userInfosList\[\d+\]\password
</param>
</result>
</action>
</package>
3、前台：
1) 页面引入jquery-142js
2) 代码如下：
<script language="javascript">
function getMsg(){
$ajax({
url:'json/returnMsgaction',
type:'post',
dataType:'json',
success:function(data){
$("#result")html(datamessage);
}
});
}
function getUser(){
$("# result ")html("");
$ajax({
url:'json/returnUseraction',
type:'post',
dataType:'json',
success:function(data){
$("#result")append("用户ID："+datauserInfouserId+"")
append("用户名："+datauserInfouserName+"")
append("密码："+datauserInfopassword+"");
}
});
}
function getUserList(){
$("# result ")html("");
$ajax({
url:'json/returnListaction',
type:'post',
dataType:'json',
success:function(data){
$each(datauserInfosList,function(i,value){
$("#result")append("第"+(i+1)+"个用户")
append("用户名："+valueuserName+"")
append("密码："+valuepassword+"");
}
}
});
}
</script>
<div id="result"></div>
<input type="button" value="获得单个消息" onclick="getMsg()"/>
<input type="button" value="获得用户信息" onclick="getUser()"/>
<input type="button" value="获得用户列表" onclick="getUserList()"/>
4、只要继承extends="json-default"，result type设置成json之后，容器会把action的属性自动封装到一个json对象中（json拦截器来做），然后调用ajax的callback方法 返回json数据
5、includeProperties 参数：输出结果中需要包含的属性值，这里正则表达式和属性名匹配，可以用“,”分割填充多个正则表达式。
如：输出UserInfo的所有属性及UserInfo的userName属性
<result type="json">
<param name="includeProperties"> userInfo,
userInfo \ userName </param>
</result>
6、excludeProperties 参数：输出结果需要剔除的属性值，也支持正则表达式匹配属性名，可以用“,”分割填充多个正则表达式，类同includeProperties
7、输出一个JSON List列表
<result name="success" type="json">
<param name="includeProperties">
userInfosList\[\d+\]\userName,userInfosList\[\d+\]\password
</param>
</result>
其中userInfosList是action中的一个List类型的属性，userInfosList \[\d+\]\ userName表示，userInfosList中存储的对象0end的userName属性（list中存储的对象必须有userName属性）。
8、为什么要用includeProperties或excludeProperties 参数：主要是为了过滤掉接口，pojo的set、list、其它对象等不需要的数据防止循环取其它关联对象或找不到接口。如果不配置,默认是处理 action中的所有属性，如果action中有接口注入，json拦截器可能找不到接口而返回不了结果，还有如果action中有一个对象，这个对象与好多对象都有关联，json拦截器会将相关联的所有对象的属性全部转换成json格式，如果其它对象有list、set,其返回结果相当庞大，有可能是死循环而无法返回 。如果不用<param name="includeProperties">或其他方式进行json数据过滤，通过debug你会发现前台返回的json字符串，是把 action中的所有属性全部转化成json字符串返回给客户端（包括service接口、pojo所有属性及有关联的pojo。有时候根本返回不了结果，也不报错，后台执行了，但前台执行不到callback function，这主要是因为找不到接口或者关联的pojo太多，造成死循环），一般情况下用的最多的就是root、 includeProperties 和excludeNullProperties参数。当然还有其他的方法，如给pojo的属性加json注解。
9、总结： action中避免使用get开头的action方法,去掉action中的接口的get方法 为json类型的result配置includeProperties, excludeProperties等参数

WebService可以有Get、 Post、Soap、Document四种方式调用，以下Java通过post方式调用WebService代码：

import javaioBufferedReader;
import javaioIOException;
import javaioInputStream;
import javaioInputStreamReader;
import javaioOutputStream;
import javaioOutputStreamWriter;
import javanetURL;
import javanetURLConnection;
import javanetURLEncoder;
import orgapachecxfendpointClient;
import orgapachecxfjaxwsendpointdynamicJaxWsDynamicClientFactory;
/
  功能描述：WebService调用
  
 /
public class ClientTest {
 /
   功能描述：>