springBoot系列：springBoot 第十篇：用spring Restdocs創(chuàng)建API文檔

這篇文章將帶你了解如何用spring官方推薦的restdoc去生成api文檔。本文創(chuàng)建一個簡單的springboot工程，將http接口通過Api文檔暴露出來。只需要通過JUnit單元測試和Spring的MockMVC就可以生成文檔。

準(zhǔn)備工作

·??????你需要15min

·??????Jdk 1.8

·??????maven 3.0+

·??????idea

引入依賴，其pom文件：

org.springframework.boot

spring-boot-starter-web

org.springframework.boot

spring-boot-starter-test

test

org.springframework.restdocs

spring-restdocs-mockmvc

test

通過@SpringBootApplication,開啟springboot

@SpringBootApplication

public?class?Application?{

public?static?void?main(String[]?args)?{

SpringApplication.run(Application.class,?args);

}

}

在springboot通常創(chuàng)建一個controller:

@RestController

public?class?HomeController?{

@GetMapping("/")

public?Map?greeting()?{

return?Collections.singletonMap("message",?"Hello?World");

}

}

啟動工程，訪問localhost:8080，瀏覽器顯示：

{“message”:”Hello World”}

證明接口已經(jīng)寫好了，但是如何通過restdoc生存api文檔呢

Restdoc,通過單元測試生成api文檔

restdocs是通過單元測試生存snippets文件，然后snippets根據(jù)插件生成htm文檔的。

建一個單元測試類：

@RunWith(SpringRunner.class)

@WebMvcTest(HomeController.class)

@AutoConfigureRestDocs(outputDir?=?"target/snippets")

public?class?WebLayerTest?{

@Autowired

private?MockMvc?mockMvc;

@Test

public?void?shouldReturnDefaultMessage()?throws?Exception?{

this.mockMvc.perform(get("/")).andDo(print()).andExpect(status().isOk())

.andExpect(content().string(containsString("Hello?World")))

.andDo(document("home"));

}

}

其中，@ AutoConfigureRestDocs注解開啟了生成snippets文件，并指定了存放位置。

啟動單元測試，測試通過，你會發(fā)現(xiàn)在target文件下生成了一個snippets文件夾，其目錄結(jié)構(gòu)如下：

└──?target

└──?snippets

└──?home

└──?httpie-request.adoc

└──?curl-request.adoc

└──?http-request.adoc

└──?http-response.adoc

默認(rèn)情況下，snippets是Asciidoctor格式的文件，包括request和reponse，另外其他兩種httpie和curl兩種流行的命令行的http請求模式。

到目前為止，只生成了Snippets文件，需要用Snippets文件生成文檔。

創(chuàng)建一個新文件src/main/asciidoc/index.adoc?：

=?用?Spring?REST?Docs?構(gòu)建文檔

This?is?an?example?output?for?a?service?running?at?http://localhost:8080:

.request

include::{snippets}/home/http-request.adoc[]

.response

include::{snippets}/home/http-response.adoc[]

這個例子非常簡單，通過單元測試和一些簡單的配置就能夠得到api文檔了。

adoc的書寫格式，參考:http://docs.spring.io/spring-restdocs/docs/current/reference/html5/，這里不多講解。

需要使用asciidoctor-maven-plugin插件，在其pom文件加上：

org.asciidoctor

asciidoctor-maven-plugin

generate-docs

prepare-package

process-asciidoc

index.adoc

html

${project.build.directory}/snippets

這時只需要通過mvnw package命令就可以生成文檔了。

在/target/generated-docs下有個index.html，打開這個html,顯示如下，界面還算簡潔：

結(jié)語

通過單元測試，生存adoc文件，再用adoc文件生存html，只需要簡單的幾步就可以生成一個api文檔的html文件，這個html文件你可以通網(wǎng)站發(fā)布出去。整個過程很簡單，對代碼無任何影響。

源碼下載：https://github.com/forezp/SpringBootLearning

參考資料

restdocs

http://docs.spring.io/spring-restdocs/docs/current/reference/html5/

方志朋簡介：SpringCloud中國社區(qū)聯(lián)合創(chuàng)始人，博客訪問量突破一千萬，愛好開源，熱愛分享，活躍于各大社區(qū)，保持著非常強(qiáng)的學(xué)習(xí)驅(qū)動力，終身學(xué)習(xí)踐行者，終身學(xué)習(xí)受益者。目前就職于國內(nèi)某家知名互聯(lián)網(wǎng)保險公司，擔(dān)任DEVOPS工程師，對微服務(wù)領(lǐng)域和持續(xù)集成領(lǐng)域研究較深，精通微服務(wù)框架SpringCloud

API Spring Spring Boot

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時內(nèi)刪除侵權(quán)內(nèi)容。

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時內(nèi)刪除侵權(quán)內(nèi)容。