用Api2Doc代替Swagger2生成 Restful API 文檔

背景介紹

在進行前后端分離式開發(fā)項目過程中，需要有效的溝通。接口文檔因為更新的不及時，也難免存在錯誤，使溝通的成本大大增加。因此，業(yè)界就出現(xiàn)了一些根據(jù)代碼自動生成 Restful API 文檔的開源項目，與 Spring Boot 結(jié)合比較好的是 Swagger2，Swagger2 通過讀取 Controller代碼中的注解信息，來自動生成 API 文檔，可以節(jié)省大量的手工編寫文檔的工作量。我之前也是用的 Swagger2，但發(fā)現(xiàn) Swagger2 也有好多地方用得不爽，如注解非常臃腫、頁面排版不太友好。想學(xué)習(xí)使用Swagger2的請參考Spring-Boot-項目中使用Swagger2。Api2Doc 專注于 Restful API 文檔的自動生成，它的原理與 Swagger2 是類似的，都是通過反射，分析 Controller 中的信息生成文檔，但它要比 Swagger2 好很多，最大的不同是Api2Doc 比 Swagger2 要少寫很多代碼。

使用Api2Doc

創(chuàng)建SpringBoot工程

具體創(chuàng)建步驟略，可參考使用STS創(chuàng)建Spring-Boot-項目。

在工程中引入Maven依賴

<dependency>
  <groupId>com.github.terran4j</groupId>
  <artifactId>terran4j-commons-api2doc</artifactId>
  <version>1.0.2</version>
</dependency>

啟用 Api2Doc 服務(wù)

在有 @SpringBootApplication 注解的類上，添加 @EnableApi2Doc
注解，以啟用 Api2Doc 服務(wù)。

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.terran4j.commons.api2doc.config.EnableApi2Doc;
@EnableApi2Doc
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

具體示例

給 Controller 類上添加文檔注解

package cn.com.yd.exam.controller;
import java.util.List;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.terran4j.commons.api2doc.annotations.Api2Doc;
import com.terran4j.commons.api2doc.annotations.ApiComment;
import com.terran4j.commons.api2doc.annotations.ApiError;
import cn.com.yd.exam.bean.User;
import cn.com.yd.exam.bean.UserType;

@Api2Doc(id = "demo1", name = "用戶接口", order = 1)
@ApiComment(seeClass = User.class)
@RestController
@RequestMapping(value = "/apis/v1/demo/users")
public class UserController {
    @Api2Doc(order = 1)
    @ApiComment("添加一個新的用戶。")
    @ApiError(value = "user.exists", comment = "此用戶已經(jīng)存在！")
    @PostMapping(name = "新增用戶",value="")
    public User addUser(
            @ApiComment("用戶所在部門名稱") @RequestParam(required = true) String dept, 
            @ApiComment("用戶名稱") @RequestParam(required = true) String name, 
            @ApiComment("用戶密碼") @RequestParam(required = true) String password, 
            @ApiComment("用戶類型") @RequestParam(required = true) UserType type) {
        User user = new User();
        user.setDept(dept).setName(name).setPassword(password).setType(type);
        return user; // TODO: 還未實現(xiàn)。
    }

    @Api2Doc(order = 2)
    @ApiComment("根據(jù)用戶id，刪除指定的用戶")
    @ApiError(value = "user.not.found", comment = "此用戶不存在！")
    @ApiError(value = "admin.cant.delete", comment = "不允許刪除管理員用戶！")
    @DeleteMapping(name = "刪除指定用戶", value = "/{id}")
    public void delete(@PathVariable("id") Long id) {

    }

    @Api2Doc(order = 3)
    @ApiComment("根據(jù)用戶id，查詢此用戶的信息")
    @ApiError(value = "user.not.found", comment = "此用戶不存在！")
    @GetMapping(name = "查詢單個用戶", value = "{id}")
    public User getUser(@PathVariable("id") Long id) {
        return null; // TODO: 還未實現(xiàn)。
    }

    @Api2Doc(order = 4)
    @ApiComment("查詢所有用戶，按注冊時間進行排序。")
    @GetMapping(name = "查詢用戶列表",value="")
    public List<User> getUsers() {
        return null; // TODO: 還未實現(xiàn)。
    }
}

User類定義

package cn.com.yd.exam.bean;
import java.util.Date;
import com.terran4j.commons.api2doc.annotations.ApiComment;
import com.terran4j.commons.restpack.RestPackIgnore;
import lombok.Data;
import lombok.experimental.Accessors;

@Data
@Accessors(chain = true)
public class User {
    @ApiComment(value = "用戶id", sample = "123")
    private Long id;

    @ApiComment(value = "用戶名", sample = "terran4j")
    private String name;

    @ApiComment(value = "賬號密碼,字母與數(shù)字的組合,區(qū)分大小寫，8-12位", sample = "sdfi23skvs")
    private String password;

    @ApiComment(value = "用戶所在的部門", sample = "研發(fā)組")
    private String dept;

    @ApiComment(value = "用戶類型", sample = "admin")
    private UserType type;

    @ApiComment(value = "是否已刪除", sample = "true")
    @RestPackIgnore
    private Boolean deleted;

    @ApiComment(value = "創(chuàng)建時間,也是注冊時間。",sample="2018-12-12")
    private Date createTime;
}

UserType枚舉定義

package cn.com.yd.exam.bean;
import com.terran4j.commons.api2doc.annotations.ApiComment;

public enum UserType {
    @ApiComment("管理員")
    admin,

    @ApiComment("普通用戶")
    user
}

運行效果

在瀏覽器中輸入http://localhost:8080/api2doc/home.html，即可訪問ApiDoc接口文檔，如下圖

api2doc.png

一些細(xì)節(jié)的設(shè)置

設(shè)置接口文檔的標(biāo)題

可在application.properties中進行接口文檔的標(biāo)題和圖標(biāo)的設(shè)置，圖標(biāo)為一個全路徑 URL，或本站點相對路徑 URL 都行。

# 中文標(biāo)題出現(xiàn)亂碼的問題，故此設(shè)置成英文的了
api2doc.title=Financial Information System APIs Document
# 圖標(biāo)為一個全路徑 URL，或本站點相對路徑 URL 都行
api2doc.icon=https://spring.io/img/homepage/icon-spring-framework.svg

開啟和關(guān)閉 Api2Doc 服務(wù)

由于Api2Doc服務(wù)沒有訪問權(quán)限校驗，建議僅在受信任的網(wǎng)絡(luò)環(huán)境如公司內(nèi)網(wǎng)中才啟用 Api2Doc 服務(wù)?？稍赼pplication.properties中配置api2doc.enabled屬性，以開啟或關(guān)閉 Api2Doc 服務(wù)，api2doc.enabled=true或者不寫表示啟用。

api2doc.enabled=false

定制歡迎頁面

每次訪問文檔頁面http://localhost:8080/api2doc/home.html 時，
中間的內(nèi)容是非常簡單的一句：

歡迎使用 Api2Doc ！

這似乎有點不太好，我們可以編寫自己的歡迎頁。
方法很簡單，在 src/main/resources 目錄下創(chuàng)建api2doc 目錄，然后在api2doc目錄下創(chuàng)建一個名為
welcome.md 的文件（這個名稱是固定的），然后用 md 語法編寫內(nèi)容就可以。

給文檔菜單項排序

可以用@Api2Doc中的order屬性給菜單項排序，order的值越小該菜單項就越排在前面。@Api2Doc既可以用在類上又可以用在方法上。

@Api2Doc(order = 4)

Api2Doc注解詳解

@Api2Doc

@Api2Doc 用于對文檔的生成進行控制。
@Api2Doc 修飾在類上，表示這個類會參與到文檔生成過程中，Api2Doc 服務(wù)會掃描 Spring 容器中所有的 Controller 類，只有類上有 @Api2Doc 的類，才會被生成文檔，一個類對應(yīng)于文檔頁面左側(cè)的一級菜單項，@Api2Doc的name 屬性則表示這個菜單項的名稱。
@Api2Doc 也可以修飾在方法，不過在方法上的 @Api2Doc 通常是可以省略，Api2Doc服務(wù)會掃描這個類的所有帶有@RequestMapping的方法，每個這樣的方法對應(yīng)文檔頁面的左側(cè)的二級菜單項，菜單項的名稱取@RequestMapping的name屬性，當(dāng)然您仍然可以在方法上用 @Api2Doc的name屬性進行重定義。

@ApiComment

@ApiComment用于對API進行說明，它可以修飾在很多地方：
修飾在類上，表示對這組API接口進行說明；
修飾在方法上，表示對這個API接口進行說明；
修飾在參數(shù)上，表示對這個API接口的請求參數(shù)進行說明；
修飾在返回類型的屬性上，表示對這個API接口的返回字段進行說明；
修飾在枚舉項上，表示對枚舉項進行說明；
如果相同名稱、相同意義的屬性或參數(shù)字段，其說明已經(jīng)在別的地方定義過了，
可以用 @ApiComment的seeClass屬性表示采用指定類的同名字段上的說明信息。

@ApiError

@ApiError用于定義錯誤碼，有的API方法在執(zhí)行業(yè)務(wù)邏輯時會產(chǎn)生錯誤，出錯后會在返回報文包含錯誤碼，以方便客戶端根據(jù)錯誤碼作進一步的處理，因此也需要在API文檔上體現(xiàn)錯誤碼的說明。

Api2Doc的缺點

Api2Doc的缺點是不能像Swagger那樣在頁面中進行測試，不過可以借助其他的工具進行測試。

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容