java快速生成接口文檔的三種解決方案

Posted on by

前言

常常在項目收尾階段，客戶需要項目的接口文檔，或者是一個大的sass平臺，各個產品之間互相調用的時候，需要對方提供接口文檔

通常來說，接口文檔屬於產品的技術沉淀，是一個長期積累的過程，然而，很多時候，開發階段並不會想的那麼多，結果到瞭需要接口文檔的時候總是疲於應付，情急之下，往往采用最笨拙的辦法，就是對照著項目代碼，一個個拷貝吧

下面針對這個情況，小編這裡給出2種簡單、快捷而適用的解決方案，幫助你快速解決這個煩惱吧

方案一，使用japidocs

這是一種最簡單也最高效的快速生成接口文檔的方式，也是對既有項目改造代價最小的方式

  • 可用於生成spring boot api文檔
  • 讀取JAVA DOC註釋，無需額外的代碼改造

基本用法

1、添加依賴

		<dependency>
            <groupId>io.github.yedaxia</groupId>
            <artifactId>japidocs</artifactId>
            <version>1.4.3</version>
        </dependency>

2、在工程的某個包下面，添加一個類

在這裡插入圖片描述

如這裡有一個TestApi的類，裡面添加一個main方，使用如下模板代碼即可，自己使用時，需要簡單修改幾處，項目根目錄，生成文檔的目錄

public class TestApi {

    public static void main(String[] args) {
        DocsConfig config = new DocsConfig();
        // 項目根目錄
        config.setProjectPath("E:\\學習代碼\\assmblyone\\web");
        // 項目名稱
        config.setProjectName("Assembly");
        // 聲明該API的版本
        config.setApiVersion("V2.0");
        // 生成API 文檔所在目錄
        config.setDocsPath("E:\\學習代碼\\assmblyone");
        // 配置自動生成
        config.setAutoGenerate(Boolean.TRUE);
        // 執行生成文檔
        Docs.buildHtmlDocs(config);
    }

}

這裡假如工程中有一個UserController接口類

@RestController
@RequestMapping(value = "/api2doc")
public class UserController {

    /**
     * 獲取用戶訊息
     * @return
     */
    @ApiComment("獲取用戶。")
    @GetMapping("/getUser")
    public User getUser() {
        User user = new User();
        user.setGroup("group1");
        user.setName("first-group");
        return user;
    }

    /**
     * 新增用戶
     * @param group 用戶組名稱
     * @param name  基礎名稱
     * @return
     */
    @ApiComment("添加新用戶")
    @GetMapping(name = "新增用戶", value = "/user")
    public String addUser(String group, String name) {
        return " group:" + group + " ==== " + "name :" + name;
    }

}

有一個實體類User

@Data
public class User {

    /**
     * id主鍵
     */
    private Long id;

    /**
     * 用戶名
     */
    private String name;

    /**
     * 賬號密碼
     */
    private String password;

    /**
     * 用戶所在的組
     */
    private String group;

    /**
     * 用戶類型
     */
    private UserType type;

    /**
     * 是否已刪除
     */
    private Boolean deleted;

    /**
     * 創建時間
     */
    private Date createTime;

}

為瞭讓生成的文檔看起來更加完善，controller的各個接口名稱，以及實體中的字段等註釋一定要盡可能完整

然後運行一下main方法，生成一下吧

在這裡插入圖片描述

然後會發現，在指定的文件目錄下，針對項目中的各個controller類，生成瞭html文檔，不妨打開看一下吧

在這裡插入圖片描述

這個效果也算很良心瞭，到這裡是不是值得小小慶賀下呢,當然對於japidocs來說，功能可不止這些，有興趣的同學可以繼續深入研究下呢

方案2，swagger + knife4j

相信使用過springboot框架的同學對swagger插件一定不陌生，springboot中集成swagger 可以幫助我們快速進行接口調試，以提升開發人員的接口調試效率

但是單純使用swagger的話，效果往往並不理想，比如想使用swagger導出一份可以交付的接口文檔的話，就有點困難瞭，這就需要swagger 配合knife4j一起使用瞭

生成步驟

1、導入相關依賴

		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>
		
		<!--swagger-ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>${swagger-bootstrap-ui.version}</version>
        </dependency>

2、添加swagger配置類

@Configuration
@EnableSwagger2
@EnableKnife4j
public class ApiSwagger2 {

    @Bean
    public Docket createRestBmbsApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("users")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.congge.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用戶相關API")
                .version("1.0")
                .build();
    }

}

3、啟動項目之後分別訪問如下地址

http://localhost:8048/swagger-ui.html

在這裡插入圖片描述

這個界面想必大傢一定很熟悉瞭，這就是swagger界面，可以在這個上面快速進行接口調試工作

http://localhost:8048/doc.html#/home

在這裡插入圖片描述

在這裡插入圖片描述

這個界面就是集成瞭knife4j之後展示出來的效果，這個效果看起來是不是更好瞭點

在這裡插入圖片描述

點就到文檔管理菜單欄，提供瞭幾種常用的可用於下載的接口文檔方式，比如我們以html為例，點擊下載，然後看一下效果如何

在這裡插入圖片描述

方案3，開源的接口文檔生成工具

這裡推薦2種

1、japi ，這是一個開源項目，git上面可以下載之後本地運行，需要安裝node環境

這裡推薦一篇文章，可供參考：https://www.jb51.net/article/218568.htm

2、使用ApiPost工具快速生成在線接口文檔

ApiPost是一個支持團隊協作，並可直接生成文檔的API調試、管理工具。它支持模擬POST、GET、PUT等常見請求，是後臺接口開發者或前端、接口測試人員不可多得的工具 。使用者不僅可以利用apiopst調試接口，還可以書寫相關註釋（接口文檔），方便的生成可讀性好、界面美觀的在線接口文檔。

使用ApiPost需要下載官方安裝包，然後本地安裝即可，官網軟件下載地址：https://www.apipost.cn/

關於ApiPost，由於其功能的強大，被很多開發人員，測試人員以及項目管理人員等廣泛使用，在小編所在的產品測試團隊，不少測試同事使用這款工具

對小編來說，所有麻煩的事情一律都采用保守的態度，但是這款工具確實值得推薦和學習，界面風格很相PostMan，這裡有一篇詳細介紹ApiPost使用的文檔，提供參考和學習：https://www.cnblogs.com/gina61/articles/12931356.html

總結

到此這篇關於java快速生成接口文檔的三種解決方案的文章就介紹到這瞭,更多相關java快速生成接口文檔內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet！

推薦閱讀：