java接口文檔怎么寫

一些剛開始寫接口文檔的服務(wù)端同學，很容易按著代碼的思路去編寫接口文檔，這讓客戶端同學或者是服務(wù)對接方技術(shù)人員經(jīng)常吐槽，看不懂接口文檔。這篇文章提供一個常規(guī)接口文檔的編寫方法，給大家參考。

成都創(chuàng)新互聯(lián)的客戶來自各行各業(yè)，為了共同目標，我們在工作上密切配合，從創(chuàng)業(yè)型小企業(yè)到企事業(yè)單位，感謝他們對我們的要求，感謝他們從不同領(lǐng)域給我們帶來的挑戰(zhàn)，讓我們激情的團隊有機會用頭腦與智慧不斷的給客戶帶來驚喜。專業(yè)領(lǐng)域包括網(wǎng)站設(shè)計制作、做網(wǎng)站、電商網(wǎng)站開發(fā)、微信營銷、系統(tǒng)平臺開發(fā)。

推薦使用的是docway?寫接口文檔，方便保存和共享，支持導出PDF MARKDOWN，支持團隊項目管理。

一、請求參數(shù)

1. 請求方法

GET

用于獲取數(shù)據(jù)

POST

用于更新數(shù)據(jù)，可與PUT互換，語義上PUT支持冪等

PUT

用于新增數(shù)據(jù)，可與POST互換，語義上PUT支持冪等

DELETE

用于刪除數(shù)據(jù)

其他

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

2. URL

url表示了接口的請求路徑。路徑中可以包含參數(shù)，稱為地址參數(shù)，如**/user/{id}**，其中id作為一個參數(shù)。

3. HTTP Header

HTTP Header用于此次請求的基礎(chǔ)信息，在接口文檔中以K-V方式展示，其中Content-Type則是一個非常必要的header，它描述的請求體的數(shù)據(jù)類型。

常用的content-type：

application/x-www-form-urlencoded

請求參數(shù)使用“”符號連接。

application/json

內(nèi)容為json格式

application/xml

內(nèi)容為xml格式

multipart/form-data

內(nèi)容為多個數(shù)據(jù)組成，有分隔符隔開

4. HTTP Body

描述http body，依賴于body中具體的數(shù)據(jù)類型。如果body中的數(shù)據(jù)是對象類型。則需要描述對象中字段的名稱、類型、長度、不能為空、默認值、說明。以表格的方式來表達最好。

示例：

二、響應(yīng)參數(shù)

1. 響應(yīng) HTTP Body

響應(yīng)body同請求body一樣，需要描述請清除數(shù)據(jù)的類型。

另外，如果服務(wù)會根據(jù)不同的http status code 返回不同的數(shù)據(jù)結(jié)構(gòu)， 也需要針對不同的http status code對內(nèi)容進行描述。

三、接口說明

說明接口的應(yīng)用場景，特別的注意點，比如，接口是否冪等、處理是同步方式還是異步方式等。

四、示例

上個示例（重點都用紅筆圈出來，記牢了）：

五、接口工具

推薦使用的是（以前叫小幺雞） 寫接口文檔，方便保存和共享，支持導出PDF MARKDOWN，支持團隊項目管理。

用java代碼實現(xiàn)客戶端與服務(wù)端建立連接？

套接字 Socket

import java.net.*;

Server:

ServerSocket server=new ServerSocket(port);//port是端口

Socket socket=server.accept();

//等待客戶機的連接請求，若連接，則創(chuàng)建一套接字，并將返回。

Client:

Socket socket=new Socket("host",port);//host主機名（本機：127.0.0.1）

java RMI客戶端也要實現(xiàn)服務(wù)端的接口嗎

兩邊是通過接口來交換信息的，當然都需要接口和它的 Stub。

你做實驗時可以考慮創(chuàng)建3個項目：

1、接口項目，只包括接口和接口編譯后的 Stub 類

2、服務(wù)端項目，只包括服務(wù)器類，它依賴接口項目。

3、客戶端項目，只包括客戶端，它依賴接口項目。

如果是從命令行運行它們，那么服務(wù)端需要服務(wù)端項目和接口項目兩個 jar，客戶端需要客戶端項目和接口項目兩個 jar，我們需要面向接口編程減少耦合程度，不要把所有類全部放在同一個項目中編譯，將來會碰到很多麻煩事，比如包名太多就可能不支持 OSGi 這種方式。

在遠程調(diào)用類的應(yīng)用中，使用靜態(tài)方法調(diào)用時一般需要接口類對應(yīng)的Stub，我們 lookup 得到的其實是 Stub （它只包括了連接到服務(wù)器的參數(shù)，然后把你想調(diào)用的”服務(wù)“ + ”參數(shù)“ 發(fā)送給服務(wù)器并將從服務(wù)器返回的結(jié)果返回給客戶端程序，因此，它其實并沒有什么”針對你的程序和服務(wù)器的特殊特性），使用動態(tài)的調(diào)用方式就完全可以做到不需要特定的 Stub 而用一個通用的方式 （也就是 RMI 編譯生成的那個 Stub 類的內(nèi)容我們來自己寫成一個框架。

上面一段是廢話，來說說怎么配置環(huán)境測試它們。

客戶端項目中只需要有接口 TestServer 和 TestServerStub 兩個類，如果你的參數(shù)本身也是一個 Remote 子類，那么參數(shù)類也需要有相應(yīng)的 Stub。

另外，我們客戶端也可以僅自帶接口類而不自帶Stub，在運行的時候可以”請求從服務(wù)器上下載一份 Stub"，如下：

System.setSecurityManager(new?RMISecurityManager());

然后在命令行添加額外參數(shù):

-Djava.security.policy=$policy?文件

-Djava.rmi.server.codebase=

這樣就可以啟用?RMI?Class?Loader?來自動從?codebase?對應(yīng)的地方查找?Stub?類，這里面?codebase?可以是一個?Http?或?Ftp?協(xié)議，注意這個?codebase?URL?后面一個?/?是必須的。那個?$policy?文件可以用?JDK\bin\policytool.exe?來生成一個。