前言
常常在項目收尾階段，客戶需要項目的接口文檔，或者是一個大的sass平臺，各個產(chǎn)品之間互相調(diào)用的時候，需要對方提供接口文檔
通常來說，接口文檔屬于產(chǎn)品的技術(shù)沉淀，是一個長期積累的過程，然而，很多時候，開發(fā)階段并不會想的那么多，結(jié)果到了需要接口文檔的時候總是疲于應(yīng)付，情急之下，往往采用最笨拙的辦法，就是對照著項目代碼，一個個拷貝吧
下面針對這個情況，小編這里給出2種簡單、快捷而適用的解決方案，幫助你快速解決這個煩惱吧
方案一，使用japidocs
這是一種最簡單也最高效的快速生成接口文檔的方式，也是對既有項目改造代價最小的方式
- 可用于生成spring boot api文檔
- 讀取JAVA DOC注釋，無需額外的代碼改造
基本用法
1、添加依賴
|
1
2
3
4
5
|
<dependency> <groupId>io.github.yedaxia</groupId> <artifactId>japidocs</artifactId> <version>1.4.3</version></dependency> |
2、在工程的某個包下面，添加一個類
如這里有一個TestApi的類，里面添加一個main方，使用如下模板代碼即可，自己使用時，需要簡單修改幾處，項目根目錄，生成文檔的目錄
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
public class TestApi { public static void main(String[] args) { DocsConfig config = new DocsConfig(); // 項目根目錄 config.setProjectPath("E:\\學(xué)習(xí)代碼\\assmblyone\\web"); // 項目名稱 config.setProjectName("Assembly"); // 聲明該API的版本 config.setApiVersion("V2.0"); // 生成API 文檔所在目錄 config.setDocsPath("E:\\學(xué)習(xí)代碼\\assmblyone"); // 配置自動生成 config.setAutoGenerate(Boolean.TRUE); // 執(zhí)行生成文檔 Docs.buildHtmlDocs(config); }} |
這里假如工程中有一個UserController接口類
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
|
@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 基礎(chǔ)名稱 * @return */ @ApiComment("添加新用戶") @GetMapping(name = "新增用戶", value = "/user") public String addUser(String group, String name) { return " group:" + group + " ==== " + "name :" + name; }} |
有一個實體類User
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
|
@Datapublic class User { /** * id主鍵 */ private Long id; /** * 用戶名 */ private String name; /** * 賬號密碼 */ private String password; /** * 用戶所在的組 */ private String group; /** * 用戶類型 */ private UserType type; /** * 是否已刪除 */ private Boolean deleted; /** * 創(chuàng)建時間 */ private Date createTime;} |
為了讓生成的文檔看起來更加完善，controller的各個接口名稱，以及實體中的字段等注釋一定要盡可能完整
然后運行一下main方法，生成一下吧
然后會發(fā)現(xiàn)，在指定的文件目錄下，針對項目中的各個controller類，生成了html文檔，不妨打開看一下吧
這個效果也算很良心了，到這里是不是值得小小慶賀下呢,當(dāng)然對于japidocs來說，功能可不止這些，有興趣的同學(xué)可以繼續(xù)深入研究下呢
方案2，swagger + knife4j
相信使用過springboot框架的同學(xué)對swagger插件一定不陌生，springboot中集成swagger 可以幫助我們快速進行接口調(diào)試，以提升開發(fā)人員的接口調(diào)試效率
但是單純使用swagger的話，效果往往并不理想，比如想使用swagger導(dǎo)出一份可以交付的接口文檔的話，就有點困難了，這就需要swagger 配合knife4j一起使用了
生成步驟
1、導(dǎo)入相關(guān)依賴
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
|
<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配置類
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
@Configuration@EnableSwagger2@EnableKnife4jpublic 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("用戶相關(guān)API") .version("1.0") .build(); }} |
3、啟動項目之后分別訪問如下地址
http://localhost:8048/swagger-ui.html
這個界面想必大家一定很熟悉了，這就是swagger界面，可以在這個上面快速進行接口調(diào)試工作
http://localhost:8048/doc.html#/home
這個界面就是集成了knife4j之后展示出來的效果，這個效果看起來是不是更好了點
點就到文檔管理菜單欄，提供了幾種常用的可用于下載的接口文檔方式，比如我們以html為例，點擊下載，然后看一下效果如何
方案3，開源的接口文檔生成工具
這里推薦2種
1、japi ，這是一個開源項目，git上面可以下載之后本地運行，需要安裝node環(huán)境
這里推薦一篇文章，可供參考：http://m.ythuaji.com.cn/article/201172.html
2、使用ApiPost工具快速生成在線接口文檔
ApiPost是一個支持團隊協(xié)作，并可直接生成文檔的API調(diào)試、管理工具。它支持模擬POST、GET、PUT等常見請求，是后臺接口開發(fā)者或前端、接口測試人員不可多得的工具 。使用者不僅可以利用apiopst調(diào)試接口，還可以書寫相關(guān)注釋（接口文檔），方便的生成可讀性好、界面美觀的在線接口文檔。
使用ApiPost需要下載官方安裝包，然后本地安裝即可，官網(wǎng)軟件下載地址：https://www.apipost.cn/
關(guān)于ApiPost，由于其功能的強大，被很多開發(fā)人員，測試人員以及項目管理人員等廣泛使用，在小編所在的產(chǎn)品測試團隊，不少測試同事使用這款工具
對小編來說，所有麻煩的事情一律都采用保守的態(tài)度，但是這款工具確實值得推薦和學(xué)習(xí)，界面風(fēng)格很相PostMan，這里有一篇詳細介紹ApiPost使用的文檔，提供參考和學(xué)習(xí)：https://www.cnblogs.com/gina61/articles/12931356.html
總結(jié)
到此這篇關(guān)于java快速生成接口文檔的三種解決方案的文章就介紹到這了,更多相關(guān)java快速生成接口文檔內(nèi)容請搜索服務(wù)器之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持服務(wù)器之家！
原文鏈接：https://blog.csdn.net/zhangcongyi420/article/details/119151683
