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. 接口文檔編寫的幾項原則

寫接口文檔時首先得知道你的讀者是接口調用方的開發人員，是除你之外需要對這個接口最熟悉的人。所以寫文檔時需要注意幾個原則：

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