0. 前言

近期忙於和各個銀行的代收介面聯調，根據遇到的問題，對之前編寫的介面進行了修改，需求收集和設計介面時想到了方方面面，生產環境下還是會遇到意想不到的問題，好在基本的執行邏輯已確定，因此只是對介面進行了一些微調，但是收錢無小事，之前在程式碼編寫時對引數進行了很多的校驗，程式碼修改之後一個引數的對不上都會導致介面呼叫的失敗，所以介面文件也要進行修改。正好趁此機會利用swagger對介面文件進行了重構，記錄一下搭建過程，也藉此談一下對介面設計及文件編寫的一點心得。

1. 專案中新增swagger外掛

引入jar包

        <dependency>
            <
 
groupId>com.fasterxml</groupId>
            <artifactId>classmate</artifactId>
            <version>1.4.0</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId
 
>jackson-databind</artifactId>
            <version>2.8.9</version>
        </dependency>

        <!-- swagger2核心依賴 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId
 
>
            <version>2.7.0</version>
        </dependency>

        <!-- swagger-ui為專案提供api展示及測試的介面 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

        <!-- spring相關jar包 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
            <version>4.2.6.RELEASE</version>
        </dependency>
   
<!-- other jars-->

後續配置Maven + SpringMVC專案整合Swagger中有介紹，這裡略過。

2. 生成介面

配置swagger只發現配置@Api註解的介面類

只對代收的類進行@Api註解標註，發現裡面的所有介面，僅為除錯，其他的方法級別的註解懶得加了

 訪問 http://localhost:8080/portal/swagger-ui.html#/

可以對每個介面進行傳參呼叫。

3. 介面文件編寫的幾項原則

寫介面文件時首先得知道你的讀者是介面呼叫方的開發人員，是除你之外需要對這個介面最熟悉的人。所以寫文件時需要注意幾個原則：

• 格式簡潔：文件需要有簡潔的書寫格式，體現在文件目錄的設計、文件目的、介面介紹語言的精煉。
• 邏輯清晰：文件內容的介紹需要具有清晰的邏輯，具體到每個介面的介紹、呼叫及返回，得有清晰的路線。
• 內容全面：介面設計的目的、請求及引數格式、響應及響應格式，最好的檢驗方法是使用者拿到該文件之後能夠自行成功的完成介面的呼叫。
• 有據可查：使用者在呼叫某介面時如果出錯，是否能夠憑藉返回資訊認識到出錯的原因進而調整，而不必呼叫失敗時一頭霧水，這需要在設計者介面設計時就設定好各種錯誤的返回標識。

4. 介面文件內容編寫

4.1 功能介紹

4.1.1 前言

主要介紹方案設計的目的、此方案所有介面共同實現的籠統的功能介紹、介面設計方和介面呼叫方（一般都是乙方。。。）各方的職責，等等

4.1.2 功能說明

詳細介紹各個介面所實現的功能，使讀者對各介面的作用有一個瞭解。內容儘量保持簡潔全面，沒必要把底層實現也寫進去。

4.2 系統介面約定

這是整個文件最重要的部分，使用者可能不會看前言和介紹，但他要實現介面呼叫，必須參考約定中的請求格式及各項約定。

4.2.1 系統約定

介紹呼叫者和提供者共同遵守的編碼約定、通訊方式（RESTful 風格介面）、資料格式（JSON 或 XML）、編碼方式（UTF-8）等。

4.2.2 介面資料格式

各個介面的請求介紹（請求引數的含義、請求地址、方法名稱、請求格式），響應介紹（響應引數介紹、響應格式）

涉及到其他檔案呼叫的也要詳細介紹檔案編寫所要遵循的格式，最好能夠內嵌附件。（如系統對賬，需要讀取ftp伺服器上的csv檔案內容與系統中比對，文件中就需要新增csv檔案的編寫規範，如：檔案命名格式、檔案內容格式、大小限制等）

4.3 返回值對照

介面呼叫成功的話返回約定好的返回值，更需要注意的是介面設計時就需要考慮到捕獲各種錯誤（可通過列舉在系統中提前定義好各種錯誤的返回值），呼叫失敗的話返回準確的提示資訊，省的呼叫方一調用出錯就來找你，對雙方的時間都是一種浪費。

5. 介面文件示例

5.1 目錄展示

5.2 介面請求部分內容

5.2.1 請求格式

介紹各個請求引數的定義和所要遵循的格式

 5.2.2 請求地址、方法及格式

5.3 介面響應部分內容

5.3.1 響應格式

介紹各個響應引數的定義和所要遵循的格式

5.3.2 響應引數格式例項

5.4 返回碼對照

定義返回碼的值，呼叫成功或失敗可參照返回碼