摘要:沒(méi)錯(cuò),不支持,從導(dǎo)出的文檔也可以看到,部分中文無(wú)法顯示,目前我也尚未找到是否有配置可以實(shí)現(xiàn)這個(gè)功能。相對(duì)前面的方式,使用起來(lái)更加簡(jiǎn)單,也可以修改配置輸出中文。
更多精彩博文,歡迎訪(fǎng)問(wèn)我的個(gè)人博客
說(shuō)明我個(gè)人是一直使用Swagger作為接口文檔的說(shuō)明的。但是由于在一些情況下,接口文檔說(shuō)明需要以文件的形式交付出去,如果再重新寫(xiě)一份文檔難免有些麻煩。于是在網(wǎng)上看到了Swagger2Markup + asciidoctor導(dǎo)出PDF的方法,百度一番后感覺(jué)網(wǎng)上的文章還是有很多沒(méi)有描述清楚的地方,遂還是硬著頭皮把官方的英文文檔大致瀏覽了一下,按照自己的思路整理出具體的步驟。
本文用到的工具:
Gradle - 4.10.3
SpringBoot - 2.1.6.RELEASE
Swagger - 2.9.2
Swagger2Markup - 1.3.3
asciidoctor
spring-restdocs-mockmvc
準(zhǔn)備Swagger數(shù)據(jù)SpringBoot中使用Swagger的過(guò)程就不再贅述了,下面是本文使用的范例:
</>復(fù)制代碼
@Configuration
@EnableSwagger2
class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.jptangchina.gradle.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2Markup Test Api")
.version("1.0")
.build();
}
}
</>復(fù)制代碼
@RestController
@RequestMapping("/user")
@Api(tags = "用戶(hù)接口")
public class UserController {
@ApiOperation("用戶(hù)登錄")
@ResponseBody
@PostMapping("/login")
public Result login(
@ApiParam(value = "用戶(hù)名", example = "jptangchina", required = true) @RequestParam String username,
@ApiParam(value = "密碼", example = "jptangchina", required = true) @RequestParam String password) {
return Result.ok();
}
}
使用org.asciidoctor.convert生成PDF(個(gè)人不推薦使用)
</>復(fù)制代碼
官方教程地址:https://github.com/Swagger2Ma...
僅為了簡(jiǎn)單的導(dǎo)出PDF而言,本文針對(duì)官方案例均有所改動(dòng),去掉了部分沒(méi)有用到的配置。
1. 獲取Swagger json文件Swagger頁(yè)面本質(zhì)上也就是對(duì)json文件進(jìn)行解析。這里需要先編寫(xiě)單元測(cè)試訪(fǎng)問(wèn)/v2/api-docs接口并將json文件保存到本地。
</>復(fù)制代碼
@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureMockMvc
class SwaggerTest {
@Autowired
private MockMvc mockMvc;
@Test
public void generateAsciiDocsToFile() throws Exception {
String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
.accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andReturn();
MockHttpServletResponse response = mvcResult.getResponse();
String swaggerJson = response.getContentAsString();
Files.createDirectories(Paths.get(outputDir));
try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
writer.write(swaggerJson);
}
}
}
</>復(fù)制代碼
System.getProperty("io.springfox.staticdocs.outputDir");來(lái)自于build.gradle中的配置
2. 將json文件轉(zhuǎn)換為adoc文件
轉(zhuǎn)換json文件需要使用到io.github.swagger2markup插件的convertSwagger2markup方法。
引入相關(guān)依賴(lài):
</>復(fù)制代碼
buildscript {
...
dependencies {
...
classpath "io.github.swagger2markup:swagger2markup-gradle-plugin:1.3.3"
}
}
apply plugin: "io.github.swagger2markup"
配置convertSwagger2markup:
</>復(fù)制代碼
ext {
asciiDocOutputDir = file("${buildDir}/asciidoc")
swaggerOutputDir = file("${buildDir}/swagger")
}
test {
systemProperty "io.springfox.staticdocs.outputDir", swaggerOutputDir
}
convertSwagger2markup {
dependsOn test
swaggerInput "${swaggerOutputDir}/swagger.json"
outputDir asciiDocOutputDir
config = [
"swagger2markup.pathsGroupedBy" : "TAGS",
]
}
</>復(fù)制代碼
更多config配置可以參考:http://swagger2markup.github....
3. 將adoc文件轉(zhuǎn)換為PDF文件
轉(zhuǎn)換PDF文件需要用到org.asciidoctor.convert插件的asciidoctor方法。
引入相關(guān)依賴(lài):
</>復(fù)制代碼
buildscript {
...
dependencies {
...
classpath "org.asciidoctor:asciidoctor-gradle-plugin:1.5.3"
}
}
apply plugin: "org.asciidoctor.convert"
手動(dòng)編寫(xiě)index.adoc文件,放置到${asciiDocOutputDir.absolutePath}中:
</>復(fù)制代碼
include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/security.adoc[]
</>復(fù)制代碼
{generated}默認(rèn)值為${build}/asciidoc,參見(jiàn):https://github.com/Swagger2Ma...
配置asciidoctor:
</>復(fù)制代碼
asciidoctor {
dependsOn convertSwagger2markup
// sourceDir中需要包含有之前手動(dòng)編寫(xiě)的index.adoc文件
sourceDir(asciiDocOutputDir.absolutePath)
sources {
include "index.adoc"
}
backends = ["pdf"]
attributes = [
doctype: "book",
toc: "left",
toclevels: "3",
numbered: "",
sectlinks: "",
sectanchors: "",
hardbreaks: "",
generated: asciiDocOutputDir
]
}
4. 編寫(xiě)一個(gè)自定義task用來(lái)執(zhí)行上述流程:
</>復(fù)制代碼
task genPdf(type: Test, dependsOn: test) {
include "**/*SwaggerTest.class"
exclude "**/*"
dependsOn(asciidoctor)
}
執(zhí)行g(shù)enPdf,就可以生成Swagger對(duì)應(yīng)的PDF文件。
5. 小結(jié)使用此方法步驟還是比較繁瑣的,總體來(lái)講就是json -> adoc -> pdf,并且使用此種方法目前有幾個(gè)比較大的問(wèn)題我仍然沒(méi)有找到解決方案:
從官方文檔中可以看到支持的語(yǔ)言默認(rèn)有EN, DE, FR, RU。沒(méi)錯(cuò),不支持CN,從導(dǎo)出的文檔也可以看到,部分中文無(wú)法顯示,目前我也尚未找到是否有配置可以實(shí)現(xiàn)這個(gè)功能。網(wǎng)上的文章部分是通過(guò)替換源代碼包里面的字體文件來(lái)實(shí)現(xiàn),但是由于后面有更好的解決方案,這里就不再討論。
從asciidoctorj-pdf的1.5.0-alpha.16版本以后(目前最新是1.5.0-alpha.18),這種方式生成文件會(huì)拋出異常,我個(gè)人并沒(méi)有深究這個(gè)異常,有興趣的讀者可以通過(guò)修改版本號(hào)試一試。
生成的adoc文件一般包含overview.adoc、paths.adoc、definitions.adoc、security.adoc一共4個(gè)文件,這也是為什么要手動(dòng)編寫(xiě)index.adoc進(jìn)行整合的原因,感覺(jué)不太方便。
綜上,我個(gè)人并不推薦采用此方式生成PDF。
build.gradle完整文件參考:
</>復(fù)制代碼
buildscript {
ext {
springbootVersion = "2.1.6.RELEASE"
}
repositories {
maven {
url "http://maven.aliyun.com/nexus/content/groups/public"
}
}
dependencies {
classpath "org.springframework.boot:spring-boot-gradle-plugin:${springbootVersion}"
classpath "org.asciidoctor:asciidoctor-gradle-plugin:1.5.3"
classpath "io.github.swagger2markup:swagger2markup-gradle-plugin:1.3.3"
}
}
repositories {
maven {
url "http://maven.aliyun.com/nexus/content/groups/public"
}
}
apply plugin: "java"
apply plugin: "maven"
apply plugin: "org.springframework.boot"
apply plugin: "io.spring.dependency-management"
apply plugin: "io.github.swagger2markup"
apply plugin: "org.asciidoctor.convert"
group "com.jptangchina"
version "1.0-SNAPSHOT"
sourceCompatibility = 1.8
targetCompatibility = 1.8
ext {
asciiDocOutputDir = file("${buildDir}/asciidoc")
swaggerOutputDir = file("${buildDir}/swagger")
swaggerVersion = "2.9.2"
}
dependencies {
compile "org.springframework.boot:spring-boot-starter-web"
compile "io.springfox:springfox-swagger2:${swaggerVersion}"
compile "io.springfox:springfox-swagger-ui:${swaggerVersion}"
compile "io.github.swagger2markup:swagger2markup:1.3.3"
asciidoctor "org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.16"
testCompile "org.springframework.boot:spring-boot-starter-test"
testCompile "org.springframework.restdocs:spring-restdocs-mockmvc"
}
test {
systemProperty "io.springfox.staticdocs.outputDir", swaggerOutputDir
}
convertSwagger2markup {
dependsOn test
swaggerInput "${swaggerOutputDir}/swagger.json"
outputDir asciiDocOutputDir
config = [
"swagger2markup.pathsGroupedBy" : "TAGS",
]
}
asciidoctor {
dependsOn convertSwagger2markup
sourceDir(asciiDocOutputDir.absolutePath)
sources {
include "index.adoc"
}
backends = ["pdf"]
attributes = [
doctype: "book",
toc: "left",
toclevels: "3",
numbered: "",
sectlinks: "",
sectanchors: "",
hardbreaks: "",
generated: asciiDocOutputDir
]
}
task genPdf(type: Test, dependsOn: test) {
include "**/*SwaggerTest.class"
exclude "**/*"
dependsOn(asciidoctor)
}
使用asciidoctor-gradle-plugin生成PDF(推薦)
asciidoctor-gradle-plugin也是官方推薦的使用方式。相對(duì)前面的方式,使用起來(lái)更加簡(jiǎn)單,也可以修改配置輸出中文。
1. 引入插件</>復(fù)制代碼
plugins {
id "org.asciidoctor.jvm.pdf" version "2.2.0"
}
2. 編寫(xiě)測(cè)試類(lèi)生成adoc
與第一中方法不同的是,不需要再將json文件保存到本地了。
</>復(fù)制代碼
@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureMockMvc
public class SwaggerTest {
@Autowired
private MockMvc mockMvc;
@Test
public void generateAsciiDocsToFile() throws Exception {
String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
.accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andReturn();
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
MockHttpServletResponse response = mvcResult.getResponse();
String swaggerJson = response.getContentAsString();
Swagger2MarkupConverter.from(swaggerJson)
.withConfig(config)
.build()
.toFile(Paths.get(outputDir + "/swagger"));
}
}
</>復(fù)制代碼
有興趣的讀者可以閱讀下toFile方法的源碼,里面對(duì)第一種方法生成的4個(gè)文件進(jìn)行了整合,這也是不再需要手動(dòng)編寫(xiě)index.adoc文件的原因。
3. 配置asciidoctorPdf
</>復(fù)制代碼
ext {
asciiDocOutputDir = file("${buildDir}/asciidoc")
// 創(chuàng)建字體與主題的文件夾
pdfFontsDir = file("${buildDir}/fonts")
pdfThemesDir = file("${buildDir}/themes")
swaggerVersion = "2.9.2"
}
pdfThemes {
local "basic", {
styleDir = pdfThemesDir
// styleName會(huì)被程序用于匹配${styleName}-theme.yml,如default-styleName-theme.yml
styleName = "default"
}
}
asciidoctorPdf{
sourceDir(asciiDocOutputDir.absolutePath)
sources {
include "swagger.adoc"
}
fontsDir(pdfFontsDir.absolutePath)
theme("basic")
}
4. 復(fù)制并修改default-theme.yml文件配置</>復(fù)制代碼
本文字體與主題文件均來(lái)自于asciidoctorj-pdf-1.5.0-alpha.18.jar源碼包,其路徑位于:gems/asciidoctorj-pdf-1.5.0-alpha.18/data
為了解決中文無(wú)法顯示的問(wèn)題,首先需要自行下載一個(gè)支持中文的字體文件。
修改主題文件,將mplus1p-regular-fallback.ttf替換為自己下載的字體文件的名稱(chēng)。
</>復(fù)制代碼
M+ 1p Fallback:
normal: your-font.ttf
bold: your-font.ttf
italic: your-font.ttf
bold_italic: your-font.ttf
</>復(fù)制代碼
由于手動(dòng)指定了字體文件的路徑,所以除了中文以外,還需要將源碼中的其他字體文件一并復(fù)制到${pdfFontsDir}文件夾。如果不愿意使用官方的字體,也可以考慮將default-theme.yml中其他的字體文件都修改為自己想要的文件。
保持task genPdf不變,再次運(yùn)行即可生成PDF文件,生成的文件默認(rèn)路徑為${build}/docs/asciidocPdf
小結(jié)asciidoctor-gradle-plugin的方式可以支持配置字體與主題,通過(guò)配置不僅規(guī)避了中文無(wú)法顯示的問(wèn)題,同時(shí)使用起來(lái)也更加簡(jiǎn)單。需要注意的是,采用此種方案生成出的文檔會(huì)在封面寫(xiě)有項(xiàng)目的版本號(hào),此版本號(hào)為build.gradle中的version,而非SwaggerConfig類(lèi)中的version。
官方提供了很多配置,可以自行參考官方文檔查看。
build.gradle完整文件參考:
</>復(fù)制代碼
buildscript {
ext {
springbootVersion = "2.1.6.RELEASE"
}
repositories {
maven {
url "http://maven.aliyun.com/nexus/content/groups/public"
}
}
dependencies {
classpath "org.springframework.boot:spring-boot-gradle-plugin:${springbootVersion}"
}
}
plugins {
id "org.asciidoctor.jvm.pdf" version "2.2.0"
}
repositories {
maven {
url "http://maven.aliyun.com/nexus/content/groups/public"
}
}
apply plugin: "java"
apply plugin: "maven"
apply plugin: "org.springframework.boot"
apply plugin: "io.spring.dependency-management"
group "com.jptangchina"
version "1.0-SNAPSHOT"
sourceCompatibility = 1.8
targetCompatibility = 1.8
ext {
asciiDocOutputDir = file("${buildDir}/asciidoc")
pdfFontsDir = file("${buildDir}/fonts")
pdfThemesDir = file("${buildDir}/themes")
swaggerVersion = "2.9.2"
}
dependencies {
compile "org.springframework.boot:spring-boot-starter-web"
compile "io.springfox:springfox-swagger2:${swaggerVersion}"
compile "io.springfox:springfox-swagger-ui:${swaggerVersion}"
compile "io.github.swagger2markup:swagger2markup:1.3.3"
testCompile "org.springframework.boot:spring-boot-starter-test"
testCompile "org.springframework.restdocs:spring-restdocs-mockmvc"
}
test {
systemProperty "io.springfox.staticdocs.outputDir", asciiDocOutputDir
}
pdfThemes {
local "basic", {
styleDir = pdfThemesDir
styleName = "default"
}
}
asciidoctorPdf{
sourceDir(asciiDocOutputDir.absolutePath)
sources {
include "swagger.adoc"
}
fontsDir(pdfFontsDir.absolutePath)
theme("basic")
}
task genPdf(type: Test, dependsOn: test) {
include "**/*SwaggerTest.class"
exclude "**/*"
dependsOn(asciidoctorPdf)
}
參考
https://github.com/Swagger2Markup/swagger2markup
https://github.com/Swagger2Markup/spring-swagger2markup-demo
http://swagger2markup.github.io/swagger2markup/1.3.3
更多精彩博文,歡迎訪(fǎng)問(wèn)我的個(gè)人博客
文章版權(quán)歸作者所有,未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為,您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請(qǐng)注明本文地址:http://m.specialneedsforspecialkids.com/yun/74990.html
摘要:日期和時(shí)間處理日期和時(shí)間的函數(shù)庫(kù)。使用中可觀察序列,創(chuàng)建異步基于事件應(yīng)用程序的函數(shù)庫(kù)。為分布式系統(tǒng)提供延遲和容錯(cuò)處理。發(fā)布使用本機(jī)格式分發(fā)應(yīng)用程序的工具。將程序資源和打包成和的本機(jī)文件。圖像處理用來(lái)幫助創(chuàng)建評(píng)估或操作圖形的函數(shù)庫(kù)。 好資源要分享原文 譯者 唐尤華 翻譯自 github akullpp 構(gòu)建 這里搜集了用來(lái)構(gòu)建應(yīng)用程序的工具。 Apache Maven:Mave...
摘要:格式文檔導(dǎo)出,是信息系統(tǒng)中非常實(shí)用的一種功能,用于各種報(bào)表和文檔的到處。示例中,使用生成要導(dǎo)出的格式文檔,通過(guò)來(lái)實(shí)現(xiàn)文件下載。將轉(zhuǎn)換成文檔生成的代碼比較簡(jiǎn)單,創(chuàng)建一個(gè)對(duì)象,然后會(huì)在指定的中輸入生成的文件。作用相當(dāng)于在中使用進(jìn)行配置。 showImg(https://segmentfault.com/img/remote/1460000008547574); PDF格式文檔導(dǎo)出,是信息系...
摘要:其標(biāo)準(zhǔn)為前身是,提供強(qiáng)大的在線(xiàn)編輯功能,包括語(yǔ)法高亮錯(cuò)誤提示自動(dòng)完成實(shí)時(shí)預(yù)覽,并且支持用戶(hù)以格式撰寫(xiě)導(dǎo)入導(dǎo)出轉(zhuǎn)換文檔。 團(tuán)隊(duì)內(nèi)部RestAPI開(kāi)發(fā)采用設(shè)計(jì)驅(qū)動(dòng)開(kāi)發(fā)的模式,即使用API設(shè)計(jì)文檔解耦前端和后端的開(kāi)發(fā)過(guò)程,雙方只在聯(lián)調(diào)與測(cè)試時(shí)耦合。在實(shí)際開(kāi)發(fā)和與前端合作的過(guò)程中,受限于眾多因素的影響,開(kāi)發(fā)效率還有進(jìn)一步提高的空間。本文的目的是優(yōu)化工具鏈支持,減少一部分重復(fù)和枯燥的勞動(dòng)。 現(xiàn)狀...
摘要:首先是從下載了,這個(gè)已經(jīng)能夠生成和文檔了,但是對(duì)中文支持不好,中文大部分會(huì)顯示為空白。關(guān)于這個(gè)對(duì)中文支持不好,查了很多資料,應(yīng)該是字體和主題的原因,所以參考了很多資料,結(jié)合當(dāng)前這個(gè),做出了最終的能很好支持中文的,最終地址。 做后端開(kāi)發(fā),自然離不開(kāi)接口文檔,接口文檔不僅方便后端開(kāi)發(fā)人員之間查看,更是前端人員必要的文檔,也有可能提供給第三方來(lái)調(diào)用我們的接口。但是,寫(xiě)接口文檔太費(fèi)時(shí)間,而且如...
摘要:在工作中,我們的前端工作流一般開(kāi)始于前后端協(xié)商好文檔之后,再針對(duì)這個(gè)文檔做模擬數(shù)據(jù),然后用做好的進(jìn)行開(kāi)發(fā),后端開(kāi)發(fā)完畢之后再改一下數(shù)據(jù)的切換到正式進(jìn)行聯(lián)調(diào)如下本文介紹的一個(gè)工具或者說(shuō)方法,來(lái)將這個(gè)工作流優(yōu)化一下,也是我平時(shí)工作正在用的方法, 在工作中,我們的前端工作流一般開(kāi)始于前后端協(xié)商好Api文檔之后,再針對(duì)這個(gè)Api文檔做mock模擬數(shù)據(jù),然后用做好的mock進(jìn)行開(kāi)發(fā),后端開(kāi)發(fā)完畢...
閱讀 3217·2023-04-26 01:30
閱讀 679·2021-11-08 13:15
閱讀 1800·2021-09-24 10:35
閱讀 1014·2021-09-22 15:41
閱讀 1938·2019-08-30 15:44
閱讀 608·2019-08-30 13:22
閱讀 1016·2019-08-30 13:06
閱讀 1208·2019-08-29 13:22