Swagger2离线文档：swagger2markup代码和插件方式

r囧r小猫 2023-07-25 09:22 43阅读 0赞

**目录**

Swagger文章汇总

Swagger2Markup简介

项目版本说明：

swagger2markup代码方式

第一步：编辑pom.xml增加需要使用的相关依赖和仓库

第二步：编写一个单元测试用例来生成执行生成文档的代码

生成AsciiDoc

生成markdown

生成confluence

swagger2markup插件方式

生成asciidoc或markdown文档

添加swagger2markup插件

生成asciidoc或markdown文档

相关说明

生成HTML文档

添加asciidoctor插件

生成HTML文档

生成PDF文档

添加asciidoctor插件

生成PDF文档

解决PDF出现乱码、空白的问题：

同时生成HTML与PDF文档

添加插件

同时生成HTML与PDF文档

--------------------

# Swagger文章汇总 #

>  *  [SpringBoot集成Swagger2，以及Swagger2常用API][SpringBoot_Swagger2_Swagger2_API]
>  *  [Swagger2离线文档：PDF和Html5格式][Swagger2_PDF_Html5]
>  *  [SpringBoot整合Shiro，Swagger2页面样式加载不出来问题][SpringBoot_Shiro_Swagger2]
>  *  [Swagger2离线文档：swagger2markup代码和插件方式][Swagger2_swagger2markup]

# Swagger2Markup简介 #

> Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。
> 
> 项目主页：[https://github.com/Swagger2Markup/swagger2markup][https_github.com_Swagger2Markup_swagger2markup]

# 项目版本说明： #

*  **spring boot 2.0.x**
 *  **swagger 2.8.0**

# swagger2markup代码方式 #

## 第一步：编辑`pom.xml`增加需要使用的相关依赖和仓库 ##

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

其中依赖组件，这两个要注意，在离线开发环境，需要自己手动添加到本地仓库

<dependency>
          <groupId>nl.jworks.markdown_to_asciidoc</groupId>
          <artifactId>markdown_to_asciidoc</artifactId>
          <version>1.0</version>
          <scope>compile</scope>
        </dependency>
    
        <dependency>
          <groupId>nl.jworks.markdown_to_asciidoc</groupId>
          <artifactId>markdown_to_asciidoc</artifactId>
          <version>1.0</version>
          <scope>compile</scope>
        </dependency>

## 第二步：编写一个单元测试用例来生成执行生成文档的代码 ##

### 生成AsciiDoc ###

@RunWith(SpringRunner.class)
    @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
    public class DemoApplicationTests {
    
        @Test
        public void generateAsciiDocs() throws Exception {
            //    输出Ascii格式
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                    .build();
    
            Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                    .withConfig(config)
                    .build()
                    .toFolder(Paths.get("src/docs/asciidoc/generated"));
        }
    
    }

*  通过Java代码来生成：只需要修改`withMarkupLanguage`属性来指定不同的格式以及`toFolder`属性为结果指定不同的输出目录。

### 生成markdown ###

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.MARKDOWN)
        .build();
    
    Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
        .withConfig(config)
        .build()
        .toFolder(Paths.get("src/docs/markdown/generated"));

### 生成confluence ###

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
        .build();
    
    Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
        .withConfig(config)
        .build()
        .toFolder(Paths.get("src/docs/confluence/generated"));

以上代码内容很简单，大致说明几个关键内容：

*  `MarkupLanguage.ASCIIDOC`：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE\_MARKUP
 *  `from(new URL("http://localhost:8080/v2/api-docs")`：指定了生成静态部署文档的源头配置，可以是这样的URL形式，也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目，我们通过使用访问本地Swagger接口的方式，如果是从外部获取的Swagger文档配置文件，就可以通过字符串或读文件的方式
 *  `toFolder(Paths.get("src/docs/asciidoc/generated")`：指定最终生成文件的具体*目录*位置

在执行了上面的测试用例之后，我们就能在当前项目的src目录下获得如下内容：

AsciiDoc

src
    --docs
    ----asciidoc
    ------generated
    --------definitions.adoc
    --------overview.adoc
    --------paths.adoc
    --------security.adoc

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZseTkxMDkwNQ_size_16_color_FFFFFF_t_70][] AsciiDoc

Markdown和Confluence

src
    --docs
    ----confluence
    ------generated
    --------definitions.txt
    --------overview.txt
    --------paths.txt
    --------security.txt
    ----markdown
    ------generated
    --------definitions.md
    --------overview.md
    --------paths.md
    --------security.md

可以看到，这种方式在运行之后就生成出了4个不同的静态文件。

**输出到单个文件**

如果不想分割结果文件，也可以通过替换`toFolder(Paths.get("src/docs/asciidoc/generated")`为`toFile(Paths.get("src/docs/asciidoc/generated/all"))`，将转换结果输出到一个单一的文件中，这样可以最终生成html的也是单一的。

# swagger2markup插件方式 #

## 生成asciidoc或markdown文档 ##

### 添加swagger2markup插件 ###

<plugin>
                    <groupId>io.github.swagger2markup</groupId>
                    <artifactId>swagger2markup-maven-plugin</artifactId>
                    <version>1.3.3</version>
                    <configuration>
                        <swaggerInput>http://localhost:9210/v2/api-docs</swaggerInput>
                        
                        <outputFile>src/docs/asciidoc/generated/all</outputFile>
    
                        
    
                        <config>
                            
                            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                            
    
                            <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
                            <swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled>
                            <swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled>
                            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                        </config>
                    </configuration>
                </plugin>

### 生成asciidoc或markdown文档 ###

>  *  运行项目
>  *  执行swagger2markup插件：maven窗口：指定项目下的Plugins.swagger2markup

### 相关说明 ###

>  *  **swaggerInput**：swagger生成的接口json数据文件。
>  *  **输出**：
>     
>      *  outputFile：输出到单一文件中
>      *  outputDir：输出到指定文件中
>  *  **swagger2markup.markupLanguage**：输出格式
>  *  **swagger2markup.outputLanguage**：语言类型：如中文（ZH），默认英语（EN）
>  *  **swagger2markup.generatedExamplesEnabled**：指定是否应该生成HTTP请求和响应示例，默认false
>  *  **swagger2markup.inlineSchemaEnabled**：是否启用参数内联
>  *  **swagger2markup.pathsGroupedBy**：api排序规则 一般用tags排序

**swagger2markup插件配置说明**

> [http://swagger2markup.github.io/swagger2markup/1.3.3/\#\_swagger2markup\_properties][http_swagger2markup.github.io_swagger2markup_1.3.3_swagger2markup_properties]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZseTkxMDkwNQ_size_16_color_FFFFFF_t_70 1][] 生成asciidoc或markdown文档

## 生成HTML文档 ##

### 添加asciidoctor插件 ###

<plugin>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>1.5.6</version>
                    <configuration>
                        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                        <backend>html5</backend>
                        <attributes>
                            
                            <toc>left</toc>
                            
                            <toclevels>3</toclevels>
                            
                            <sectnums>true</sectnums>
                        </attributes>
                    </configuration>
                </plugin>

### 生成HTML文档 ###

>  *  生成asciidoc文档
>  *  执行插件：maven窗口：指定项目下的Plugins.asciidoctor.asciidoctor:process-asciidoc

相关说明

>  *  **sourceDirectory**：asciidoc文档所在目录
>  *  **outputDirectory**：HTML的输出目录
>  *  **backend**：类型

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZseTkxMDkwNQ_size_16_color_FFFFFF_t_70 2][] 生成HTML文档

## 生成PDF文档 ##

### 添加asciidoctor插件 ###

<plugin>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>1.5.6</version>
                    <configuration>
                      <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                        <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                        <backend>pdf</backend>
                    </configuration>
                    <dependencies>
                        <dependency>
                            <groupId>org.asciidoctor</groupId>
                            <artifactId>asciidoctorj-pdf</artifactId>
                            <version>1.5.0-alpha.16</version>
                        </dependency>
                    </dependencies>
                </plugin>

### 生成PDF文档 ###

>  *  生成asciidoc文档
>  *  执行插件：maven窗口：指定项目下的Plugins.asciidoctor.asciidoctor:process-asciidoc

### 解决PDF出现乱码、空白的问题： ###

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ZseTkxMDkwNQ_size_16_color_FFFFFF_t_70 3][] PDF出现乱码、空白的问题

*  maven仓库中的asciidoctorj-pdf jar包，使用压缩工具打开：
    
     *  进入asciidoctorj-pdf-1.5.0-alpha.16.jar\\gems\\asciidoctor-pdf-1.5.0.alpha.16\\data\\ 目录
     *  fonts：字体文件目录
     *  themes：配置文件目录
 *  下载字体：
    
     *  字体下载：https://github.com/chloerei/asciidoctor-pdf-cjk-kai\_gen\_gothic/releases
     *  注：只需下载KaiGenGothicCN-Bold.ttf、KaiGenGothicCN-Bold-Italic.ttf、KaiGenGothicCN-Bold-Italic.ttf、KaiGenGothicCN-Bold-Italic.ttf 即可
     *  将字体文件放入fonts目录中
 *  修改配置
    
     *  进入themes目录，修改default-theme.yml文件
     *  修改以base:font\_family属性值对应的字体文件配置：在font:catalog下。
    
        base:
          font_family: Noto Serif
        
        font:
          catalog:
            Noto Serif:
              normal: KaiGenGothicCN-Regular.ttf
              bold: KaiGenGothicCN-Bold.ttf
              italic: KaiGenGothicCN-Regular-Italic.ttf
              bold_italic: KaiGenGothicCN-Bold-Italic.ttf

## 同时生成HTML与PDF文档 ##

### 添加插件 ###

<plugin>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>1.5.6</version>
                    <configuration>
                      <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    </configuration>
                    <dependencies>
                        <dependency>
                            <groupId>org.asciidoctor</groupId>
                            <artifactId>asciidoctorj-pdf</artifactId>
                            <version>1.5.0-alpha.16</version>
                        </dependency>
                    </dependencies>
                    <executions>
                        <execution>
                            <id>output-html</id>
                            <phase>generate-resources</phase>
                            <goals>
                                <goal>process-asciidoc</goal>
                            </goals>
                            <configuration>
                                <backend>html5</backend>
                           <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                                <attributes>
                                    
                                    <toc>left</toc>
                                    
                                    <toclevels>3</toclevels>
                                    
                                    <sectnums>true</sectnums>
                                </attributes>
                            </configuration>
                        </execution>
                        <execution>
                            <id>output-pdf</id>
                            <phase>generate-resources</phase>
                            <goals>
                                <goal>process-asciidoc</goal>
                            </goals>
                            <configuration>
                                <backend>pdf</backend>
                            <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>

### 同时生成HTML与PDF文档 ###

>  *  生成asciidoc文档
>  *  执行插件：maven窗口：指定项目下的Plugins.asciidoctor.asciidoctor:process-asciidoc
>  *  生成文档（二者选其一）：注：此步骤耗时，大概七八分钟
>     
>      *  执行命令mvn generate-resources
>      *  使用idea设置快捷启动：run/debug configurations -> maven -> command line:generate-resources，执行

**PDFPDF出现乱码、空白的问题**

>  *  参考单独生成PDF问题解决