怎么用java快速生成接口文檔

本篇內容主要講解“怎么用java快速生成接口文檔”，感興趣的朋友不妨來看看。本文介紹的方法操作簡單快捷，實用性強。下面就讓小編來帶大家學習“怎么用java快速生成接口文檔”吧!

目錄

• 前言

• 方案一，使用japidocs

• 基本用法

• 方案2，swagger + knife4j

• 生成步驟

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

前言

常常在項目收尾階段，客戶需要項目的接口文檔，或者是一個大的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環境

這里推薦一篇文章，可供參考：http://www.neiyidaogou.com/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快速生成接口文檔”有了更深的了解，不妨來實際操作一番吧！這里是億速云網站，更多相關內容可以進入相關頻道進行查詢，關注我們，繼續學習！