最近需要設計一個API伺服器，想要把API介面搞得規範一下，就通過網上搜集到了一些資料，以下便是自己的一些理解以及相關的具體實現

本文采用的是spring boot+maven的方案

restful規範

這個規範我在這裡也不打算長篇大論地講解，怎麼說呢，有人喜歡有人討厭，我也不去爭，因為我經驗不多，看法和大佬有所不同。

restful規範簡單來說，就是通過一些關鍵字去定義url介面，從而讓url具有更好的可讀性，如下面舉個例子

# 查詢所有使用者
http://localhost:9200/shunbang/api/user/users
# 指定id為1的使用者
http://localhost:9200/shunbang/api/user/users/1
# 資料太多，只要前10
http://localhost:9200/shunbang/api/user/users?limit=10
# 從第十條資料後開始（不要前十條資料）
http://localhost:9200/shunbang/api/user/users?offset=10
 

我覺得restful規範起來，url的可讀性較好

restful規範使用的幾種方式

url請求協議介紹

API文件生成框架 smart-doc

介紹

這裡，我使用了smart-doc這款框架，可以無侵入實現API介面的註釋，需要在Controller和實體類中添加註釋

使用

使用此開源庫很簡單，我們只需要在maven專案中新增外掛的依賴即可

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>1.0.2</version>
    <configuration>
        <!--指定生成文件的使用的配置檔案,配置檔案放在自己的專案中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定專案名稱-->
        <projectName>測試</projectName>
        <!--smart-doc實現自動分析依賴樹載入第三方依賴的原始碼，如果一些框架依賴庫載入不到導致報錯，這時請使用excludes排除掉-->
        <excludes>
            <!--格式為：groupId:artifactId;參考如下-->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在執行編譯時啟動smart-doc，則將phase註釋掉-->
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>
 

之後，在resources資料夾中新建smart-doc.json檔案，進行一些配置即可

{
  "outPath": "Q:\\JavaWebProject\\shunbang\\target", //指定文件的輸出路徑
  "serverUrl": "http://localhost:9200/shunbang", //設定伺服器地址,非必須
//  "serverUrl": "http://47.101.148.199:9200/shunbang", //設定伺服器地址,非必須
  "isStrict": false, //是否開啟嚴格模式
  "allInOne": true  //是否將文件合併到一個檔案中，一般推薦為true
}

我這裡沒開啟嚴格模式，若是開啟了嚴格模式，則呼叫外掛的時候就會報錯

之後直接在旁邊的外掛找到，選擇對應生成的文件

之後就可以在輸出資料夾中找到html檔案了

開啟網頁，就會有詳細的文件了

補充

JsonIgnore註解

若是存在某些敏感欄位不需要被返回，在實體類的欄位中新增JsonIgnore註解(注意：此JsonIgnore註解為spring boot內建jackson框架自帶)

public class JacksonAnnotation {

    /**
     * 使用者名稱
     */

    @JsonProperty("name")
    private String username;


    /**
     * 身份證號
     */
    @JsonIgnore
    private String idCard;
}

Fastjson使用 @JSONField(serialize = false),起關鍵作用的是serialize = false

mock註解

smart-doc會在生成的文件的例子中進行自動隨機賦值，如下圖

如果不想隨機賦值，可以使用mock註解指定例子中的資料

ignore註解

這個是smart-doc自帶的註解，寫在實體類欄位的註釋上，生成的API文件就會忽略此欄位

更多詳情，請參考官方文件

具體編碼

spring boot中其實內建了GetMapping、PostMapping、PutMapping、DeleteMapping，分別對應的不同的請求方式，如果使用了以上註解，那麼傳送url請求的方式也是應該相對應，否則伺服器不會進行資料的返回

1.指定id

想要通過http://localhost:9200/shunbang/api/user/users/1查詢指定id使用者資訊

使用PathVariable註解

/**
 * 查詢指定id的使用者資訊
 *
 * @param id 使用者id
 * @return 使用者資訊
 */
@GetMapping("{id}")
public User selectByPk(@PathVariable("id") Integer id) {
    return userMapper.selectOne(new QueryWrapper<User>().eq("user_id", id));
}

2.limit限制

想要通過http://localhost:9200/shunbang/api/user/users?limit=10來獲得前幾條記錄，limit此引數是可選的，使用RequestParam註解

當用戶沒有輸入limit引數，則顯示返回所有的資料，有的話則進行資料的限制，offset也是同理，之後便不多說了

/**
 * 查詢所有使用者
 *
 * @return 使用者列表的json
 */
@GetMapping("users")
public List<User> selectAll(@RequestParam(required = false) Integer limit) {
    if (limit == null) {
        return userMapper.selectList(null);
    } else {
        System.out.println(limit);
        return userMapper.selectList(null);
    }
}

3.傳遞實體類

原本我是想要通過http://localhost:9200/shunbang/api/user/update?jsonData=xx這樣傳遞實體類的json資料，之後由後臺接收json資料，並再將json資料轉為實體類物件，呼叫update方法，進行表記錄的update

其實，有個方法比上面的方法更簡單，使用RequestBody註解，之後進行put的請求，將json資料直接通過body傳遞

@PutMapping("update")
public boolean updateUser(@RequestBody User user) {
    return user.updateById();
}

Java傳送url請求

HttpURLConnection conn =new URL("address").openConnection();
conn.setRequestMethod("PUT"); // 可以根據需要 提交 GET、POST、DELETE、PUT等http提供的功能
conn.setRequestProperty("Content-Type", " application/json");//設定 請求格式 json，也可以設定xml格式的

上述是原生的，之後我會在補充使用okhttp框架進行相關的介面申請資料

我是使用的postwoman進行API的測試

參考

smart-doc
SpringBoot RestFul風格API介面開發
Post 方法引數寫在body中和寫在url中有什麼區別？知乎嚴振杰回