Swagger 导出 PDF

最下面附加了自己处理中文缺失的问题的解决办法

加入依赖

Properties


<properties>
    <java.version>1.8</java.version>
    <swagger2markup.version>1.3.1</swagger2markup.version>
    <asciidoctor.input.directory>${project.build.directory}/src/docs/asciidoc/generated</asciidoctor.input.directory>
    <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
    <generated.asciidoc.directory>${project.build.directory}/src/docs/asciidoc/generated</generated.asciidoc.directory>
    <swagger.input>http://localhost:8080/v2/api-docs</swagger.input>
    <jackson.version>2.9.6</jackson.version>
 </properties>

repository


<repositories>
     <repository>
         <id>jcentral</id>
         <name>bintray</name>
         
         <snapshots>
             <enabled>false</enabled>
         </snapshots>
     </repository>
     <repository>
         <id>jcenter-snapshots</id>
         <name>jcenter</name>
         <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
     </repository>
</repositories>
<pluginRepositories>
     <pluginRepository>
         <id>jcenter-snapshots</id>
         <name>jcenter</name>
         <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
     </pluginRepository>
     <pluginRepository>
         <snapshots>
             <enabled>false</enabled>
         </snapshots>
         <id>jcenter-releases</id>
         <name>jcenter</name>
         
     </pluginRepository>
</pluginRepositories>

dependency

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>${swagger2markup.version}</version>
</dependency>

① plugin swagger2markup

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>${swagger2markup.version}</version>
    <!--<dependencies>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-import-files-ext</artifactId>
            <version>${swagger2markup.version}</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>${swagger2markup.version}</version>
        </dependency>
    </dependencies>-->
    <configuration>
        <swaggerInput>${swagger.input}</swaggerInput>
        <outputDir>${generated.asciidoc.directory}</outputDir>
        <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
    </configuration>
    <executions>
        <execution>
            <phase>test</phase>
            <goals>
                 <goal>convertSwagger2markup</goal>
            </goals>
        </execution>
    </executions>
</plugin>

② plugin asciidoctor

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <!-- Include Asciidoctor PDF for pdf generation -->
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.16</version>
        </dependency>
        <dependency>
            <groupId>org.jruby</groupId>
            <artifactId>jruby-complete</artifactId>
            <version>1.7.24</version>
        </dependency>
    </dependencies>
    <!-- Configure generic document generation settings -->
    <configuration>
        <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
        <!--<sourceDocumentName>overview.adoc</sourceDocumentName>-->
        <!--<sourceDocumentName>definitions.adoc</sourceDocumentName>-->
        <sourceDocumentName>paths.adoc</sourceDocumentName>
        <!--<sourceDocumentName>security.adoc</sourceDocumentName>-->
        <headerFooter>true</headerFooter>
        <doctype>book</doctype>
        <backend>pdf</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <toc>left</toc>
            <toclevels>3</toclevels>
            <sectnums>true</sectnums>
            <generated>${generated.asciidoc.directory}</generated>
        </attributes>
    </configuration>
</plugin>

操作步骤：

A Properties中的 <swagger.input> 记得改一下port 和 context-path

然后再启动项目

B 执行插件一（或使用指令 mvn swagger2markuo:convertSwagger2markup）

文件会生成在插件一配置中 <outputDir> 的设定的路径下（须新建该路径）

会生成四个 .adoc文件，分别是

definitions.adoc

overview.adoc

paths.adoc

security.adoc

C 插件二中的配置，<sourceDocumentName> 代表要转换的文件（如果设置多个标签，也只会执行最后一个标签）；<backend> 代表将要转换的文件类型，可使用 pdf 或 html

插件二的执行可以使用命令 mvn asciidoctor:process-asciidoc

问题记录

插件二中，默认使用的 asciidoctorj-pdf 依赖对中文的支持不太友好，会出现部分文字变成空格的情况。

找到我使用的对应的jar包，

C:\Users\NagaSiren.m2\repository\org\asciidoctor\asciidoctorj-pdf\1.5.0-alpha.16\asciidoctorj-pdf-1.5.0-alpha.16.jar

1、解压该jar包，进入路径gems\asciidoctor-pdf-1.5.0.alpha.16\data\fonts

添加一些自己的中文格式的ttf文件，本人是在 C://Windows/font里面找的一个系统的 simkai.ttf文档

2、更改gems\asciidoctor-pdf-1.5.0.alpha.16\data\themes中的文件default-theme.yml

更改以下属性即可，将原来的默认字体依赖改为我们新增的ttf(不要更改缩进)

 Noto Serif:
     normal: simkai.ttf
     bold: simkai.ttf
     italic: simkai.ttf
     bold_italic: simkai.ttf

最后替换掉jar中的这个yml配置文件，字体就正常了。

示例图片

全部栏目