使用 Swagger2 生成在线文档和 PDF

Java 2018-10-24

使用 Swagger2 生成在线文档和 PDF

2018-10-24

Java

在线文档之前有写过注解的说明

但网络上很少有提及离线文档的生成和其中解决中文乱码的问题

博客中的东西基本都是抄来抄去的东西

以下特此记录一下使用中的坑

SpringBoot中的Start

推荐的版本，相对来说比较好用。

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.8.0.RELEASE</version>
</dependency>

入口类上加：@EnableSwagger2Doc 注解用以启用在线文档及自动配置。

application.yml 中的配置：

swagger.enabled=是否启用swagger，默认：true
swagger.title=标题
swagger.description=描述
swagger.version=版本
swagger.license=许可证
swagger.licenseUrl=许可证URL
swagger.termsOfServiceUrl=服务条款URL
swagger.contact.name=维护人
swagger.contact.url=维护人URL
swagger.contact.email=维护人email
swagger.base-package=swagger扫描的基础包，默认：全扫描
swagger.base-path=需要处理的基础URL规则，默认：/**
swagger.exclude-path=需要排除的URL规则，默认：空
swagger.host=文档的host信息，默认：空

通常用以排除SpringBoot自带的错误处理接口
swagger.exclude-path= /error
通常用以关闭自带的错误码，例如403、404等。必须至少配置一个code代码。
apply-default-response-messages: false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=error

Maven插件生成PDF和HTML文档

记得关注官方示例中的配置，版本号一定要和示例中一致

重要的事情说三次，因为不一致的版本会导致各种奇葩的问题。

所以在这里需要要特别注意。

这里需要引入两个Maven插件和一个依赖

并且要配置两个额外仓库，中心仓库基本无法下载依赖项中的内容。

依赖配置：

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
</dependency>

仓库配置：


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

<repositories>
    <repository>
        <id>jcentral</id>
        <name>bintray</name>
        <url>http://jcenter.bintray.com</url>
        <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>

插件配置：

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
</plugin>

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

            <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
            <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
            <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
            <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath>
            <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</swagger2markup.extensions.springRestDocs.snippetBaseUri>
            <swagger2markup.extensions.springRestDocs.defaultSnippets>true</swagger2markup.extensions.springRestDocs.defaultSnippets>
            <swagger2markup.pathSecuritySectionEnabled>false</swagger2markup.pathSecuritySectionEnabled>
        </config>
    </configuration>
    <executions>
        <execution>
            <phase>test</phase>
            <goals>
                <goal>convertSwagger2markup</goal>
            </goals>
        </execution>
    </executions>
</plugin>

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>

    <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.21</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
        <sourceDocumentName>index.adoc</sourceDocumentName>
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>3</toclevels>
            <numbered></numbered>
            <hardbreaks></hardbreaks>
            <sectlinks></sectlinks>
            <sectanchors></sectanchors>
            <generated>${generated.asciidoc.directory}</generated>
        </attributes>
    </configuration>

    <executions>
        <execution>
            <id>output-html</id>
            <phase>test</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
            </configuration>
        </execution>

        <execution>
            <id>output-pdf</id>
            <phase>test</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

参数配置：


<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>

    <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory>
    <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
    <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>
    <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>
    <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
    <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
    <swagger.input>http://localhost/v2/api-docs</swagger.input>
</properties>

由于参数配置中指定index.adoc用于合并文档，需要建立

src/docs/asciidoc/index.adoc文档来指定合并内容。

index.adoc的内容如下：

include::{generated}/overview.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/security.adoc[]

include::example.adoc[]

以下是各项合并项的解释：

include::{generated}/overview.adoc[]：描述总体大纲
include::{generated}/definitions.adoc[]：描述详细参数
include::{generated}/paths.adoc[]：描述路径接口
include::{generated}/security.adoc[]：描述接口的安全配置

example.adoc：为自定义的追加文档内容，这里可以写一些自己定义的内容。

example.adoc的位置为：src/docs/asciidoc/example.adoc

不想显示的合并内容可以直接删除掉。

要想使这两个插件联合工作，需要执行Maven中的Test生命周期。不要单独使用Maven插件。

由于配置了swaggerJson数据源为在线数据源：http://localhost/v2/api-docs

在执行Test生命周期前，应启动程序实例来为插件提供数据。

Test生命周期结束后会在配置的目录中生成PDF和HTML文档。

解决中文缺字问题

其实缺字问题的原因也很简单，插件中依赖的PDF生成库 asciidoctorj-pdf 自带的字体本身就不支持中文。

所以生成的PDF文档自然就缺字了。

解决的思路是到本地仓库中为这个依赖仓库添加支持中文的字体就好。

解决流程：

找到 asciidoctorj-pdf-1.5.0-alpha.16.jar
向 asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\fonts 目录中添加支持中文的字体。

注意这里只支持ttf字体，otf字体无法被插件识别
3. 修改 asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\theme\default-theme.yml 配置文件

font:
  catalog:
    # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
    Noto Serif:
      normal: 支持中文的字体.ttf
      bold: 支持中文的字体.ttf
      italic: 支持中文的字体.ttf
      bold_italic: 支持中文的字体.ttf

用修改后的库重新生成的PDF即可完美显示中文文字。