国产xxxx99真实实拍_久久不雅视频_高清韩国a级特黄毛片_嗯老师别我我受不了了小说

資訊專欄INFORMATION COLUMN

Gradle環境下導出Swagger為PDF

OnlyMyRailgun / 3133人閱讀

摘要：沒錯，不支持，從導出的文檔也可以看到，部分中文無法顯示，目前我也尚未找到是否有配置可以實現這個功能。相對前面的方式，使用起來更加簡單，也可以修改配置輸出中文。

更多精彩博文，歡迎訪問我的個人博客

說明

我個人是一直使用Swagger作為接口文檔的說明的。但是由于在一些情況下，接口文檔說明需要以文件的形式交付出去，如果再重新寫一份文檔難免有些麻煩。于是在網上看到了Swagger2Markup + asciidoctor導出PDF的方法，百度一番后感覺網上的文章還是有很多沒有描述清楚的地方，遂還是硬著頭皮把官方的英文文檔大致瀏覽了一下，按照自己的思路整理出具體的步驟。

本文用到的工具：

Gradle - 4.10.3

SpringBoot - 2.1.6.RELEASE

Swagger - 2.9.2

Swagger2Markup - 1.3.3

asciidoctor

spring-restdocs-mockmvc

準備Swagger數據

SpringBoot中使用Swagger的過程就不再贅述了，下面是本文使用的范例：

@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();
    }
}
@RestController
@RequestMapping("/user")
@Api(tags = "用戶接口")
public class UserController {

    @ApiOperation("用戶登錄")
    @ResponseBody
    @PostMapping("/login")
    public Result login(
        @ApiParam(value = "用戶名", example = "jptangchina", required = true) @RequestParam String username,
        @ApiParam(value = "密碼", example = "jptangchina", required = true) @RequestParam String password) {
        return Result.ok();
    }
}
使用org.asciidoctor.convert生成PDF（個人不推薦使用） 
官方教程地址：https://github.com/Swagger2Ma...

僅為了簡單的導出PDF而言，本文針對官方案例均有所改動，去掉了部分沒有用到的配置。

1. 獲取Swagger json文件

Swagger頁面本質上也就是對json文件進行解析。這里需要先編寫單元測試訪問/v2/api-docs接口并將json文件保存到本地。

@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);
        }
    }

}
System.getProperty("io.springfox.staticdocs.outputDir");來自于build.gradle中的配置
2. 將json文件轉換為adoc文件

轉換json文件需要使用到io.github.swagger2markup插件的convertSwagger2markup方法。

引入相關依賴：

buildscript {
    ...
    dependencies {
        ...
        classpath "io.github.swagger2markup:swagger2markup-gradle-plugin:1.3.3"
    }
}
  
apply plugin: "io.github.swagger2markup"

配置convertSwagger2markup：

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",
    ]
}
更多config配置可以參考：http://swagger2markup.github....
3. 將adoc文件轉換為PDF文件

轉換PDF文件需要用到org.asciidoctor.convert插件的asciidoctor方法。
引入相關依賴：

buildscript {
    ...
    dependencies {
        ...
        classpath "org.asciidoctor:asciidoctor-gradle-plugin:1.5.3"
    }
}
apply plugin: "org.asciidoctor.convert"

手動編寫index.adoc文件，放置到${asciiDocOutputDir.absolutePath}中：

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/security.adoc[]
{generated}默認值為${build}/asciidoc，參見：https://github.com/Swagger2Ma...

配置asciidoctor：

asciidoctor {
    dependsOn convertSwagger2markup
    // sourceDir中需要包含有之前手動編寫的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. 編寫一個自定義task用來執行上述流程： 
task genPdf(type: Test, dependsOn: test) {
    include "**/*SwaggerTest.class"
    exclude "**/*"
    dependsOn(asciidoctor)
}

執行genPdf，就可以生成Swagger對應的PDF文件。

5. 小結

使用此方法步驟還是比較繁瑣的，總體來講就是json -> adoc -> pdf，并且使用此種方法目前有幾個比較大的問題我仍然沒有找到解決方案：

從官方文檔中可以看到支持的語言默認有EN, DE, FR, RU。沒錯，不支持CN，從導出的文檔也可以看到，部分中文無法顯示，目前我也尚未找到是否有配置可以實現這個功能。網上的文章部分是通過替換源代碼包里面的字體文件來實現，但是由于后面有更好的解決方案，這里就不再討論。

從asciidoctorj-pdf的1.5.0-alpha.16版本以后（目前最新是1.5.0-alpha.18），這種方式生成文件會拋出異常，我個人并沒有深究這個異常，有興趣的讀者可以通過修改版本號試一試。

生成的adoc文件一般包含overview.adoc、paths.adoc、definitions.adoc、security.adoc一共4個文件，這也是為什么要手動編寫index.adoc進行整合的原因，感覺不太方便。

綜上，我個人并不推薦采用此方式生成PDF。

build.gradle完整文件參考：

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也是官方推薦的使用方式。相對前面的方式，使用起來更加簡單，也可以修改配置輸出中文。

1. 引入插件 
plugins {
    id "org.asciidoctor.jvm.pdf" version "2.2.0"
}
2. 編寫測試類生成adoc

與第一中方法不同的是，不需要再將json文件保存到本地了。

@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"));
    }
}
有興趣的讀者可以閱讀下toFile方法的源碼，里面對第一種方法生成的4個文件進行了整合，這也是不再需要手動編寫index.adoc文件的原因。
3. 配置asciidoctorPdf 
ext {
    asciiDocOutputDir = file("${buildDir}/asciidoc")
    // 創建字體與主題的文件夾
    pdfFontsDir = file("${buildDir}/fonts")
    pdfThemesDir = file("${buildDir}/themes")
    swaggerVersion = "2.9.2"
}

pdfThemes {
    local "basic", {
        styleDir = pdfThemesDir
        // styleName會被程序用于匹配${styleName}-theme.yml，如default-styleName-theme.yml
        styleName = "default"
    }
}
asciidoctorPdf{
    sourceDir(asciiDocOutputDir.absolutePath)
    sources {
        include "swagger.adoc"
    }
    fontsDir(pdfFontsDir.absolutePath)
    theme("basic")
}
本文字體與主題文件均來自于asciidoctorj-pdf-1.5.0-alpha.18.jar源碼包，其路徑位于：gems/asciidoctorj-pdf-1.5.0-alpha.18/data
4. 復制并修改default-theme.yml文件配置

為了解決中文無法顯示的問題，首先需要自行下載一個支持中文的字體文件。

修改主題文件，將mplus1p-regular-fallback.ttf替換為自己下載的字體文件的名稱。

M+ 1p Fallback:
  normal: your-font.ttf
  bold: your-font.ttf
  italic: your-font.ttf
  bold_italic: your-font.ttf
由于手動指定了字體文件的路徑，所以除了中文以外，還需要將源碼中的其他字體文件一并復制到${pdfFontsDir}文件夾。如果不愿意使用官方的字體，也可以考慮將default-theme.yml中其他的字體文件都修改為自己想要的文件。

保持task genPdf不變，再次運行即可生成PDF文件，生成的文件默認路徑為${build}/docs/asciidocPdf

小結

asciidoctor-gradle-plugin的方式可以支持配置字體與主題，通過配置不僅規避了中文無法顯示的問題，同時使用起來也更加簡單。需要注意的是，采用此種方案生成出的文檔會在封面寫有項目的版本號，此版本號為build.gradle中的version，而非SwaggerConfig類中的version。

官方提供了很多配置，可以自行參考官方文檔查看。

build.gradle完整文件參考：

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

更多精彩博文，歡迎訪問我的個人博客

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/74990.html

相關文章

  • 國外程序員整理的Java資源大全

    摘要：日期和時間處理日期和時間的函數庫。使用中可觀察序列，創建異步基于事件應用程序的函數庫。為分布式系統提供延遲和容錯處理。發布使用本機格式分發應用程序的工具。將程序資源和打包成和的本機文件。圖像處理用來幫助創建評估或操作圖形的函數庫。 好資源要分享原文 譯者 唐尤華 翻譯自 github akullpp 構建 這里搜集了用來構建應用程序的工具。 Apache Maven：Mave...

    chengtao1633 評論0 收藏0

  • Spring Boot集成Freemarker和iText生成PDF文檔

    摘要：格式文檔導出，是信息系統中非常實用的一種功能，用于各種報表和文檔的到處。示例中，使用生成要導出的格式文檔，通過來實現文件下載。將轉換成文檔生成的代碼比較簡單，創建一個對象，然后會在指定的中輸入生成的文件。作用相當于在中使用進行配置。 showImg(https://segmentfault.com/img/remote/1460000008547574); PDF格式文檔導出，是信息系...

    liujs 評論0 收藏0

  • 【效率專精系列】善用API統一描述語言提升RestAPI開發效率

    摘要：其標準為前身是，提供強大的在線編輯功能，包括語法高亮錯誤提示自動完成實時預覽，并且支持用戶以格式撰寫導入導出轉換文檔。 團隊內部RestAPI開發采用設計驅動開發的模式，即使用API設計文檔解耦前端和后端的開發過程，雙方只在聯調與測試時耦合。在實際開發和與前端合作的過程中，受限于眾多因素的影響，開發效率還有進一步提高的空間。本文的目的是優化工具鏈支持，減少一部分重復和枯燥的勞動。 現狀...

    tianyu 評論0 收藏0

  • 使用spring boot + swagger自動生成HTML、PDF接口文檔，并解決中文顯示為空白

    摘要：首先是從下載了，這個已經能夠生成和文檔了，但是對中文支持不好，中文大部分會顯示為空白。關于這個對中文支持不好，查了很多資料，應該是字體和主題的原因，所以參考了很多資料，結合當前這個，做出了最終的能很好支持中文的，最終地址。 做后端開發，自然離不開接口文檔，接口文檔不僅方便后端開發人員之間查看，更是前端人員必要的文檔，也有可能提供給第三方來調用我們的接口。但是，寫接口文檔太費時間，而且如...

    fjcgreat 評論0 收藏0

  • 使用API自動生成工具優化前端工作流

    摘要：在工作中，我們的前端工作流一般開始于前后端協商好文檔之后，再針對這個文檔做模擬數據，然后用做好的進行開發，后端開發完畢之后再改一下數據的切換到正式進行聯調如下本文介紹的一個工具或者說方法，來將這個工作流優化一下，也是我平時工作正在用的方法， 在工作中，我們的前端工作流一般開始于前后端協商好Api文檔之后，再針對這個Api文檔做mock模擬數據，然后用做好的mock進行開發，后端開發完畢...

    GeekQiaQia 評論0 收藏0

發表評論

0條評論

最新活動
閱讀需要支付1元查看
<