swagger2markup生成静态文档（插件版）

swagger2markup生成静态文档（插件版）

生成asciidoc或markdown文档

添加swagger2markup插件

<plugin>
                <groupId>io.github.swagger2markupgroupId>
                <artifactId>swagger2markup-maven-pluginartifactId>
                <version>1.3.3version>
                <configuration>
                    <swaggerInput>http://localhost:9210/v2/api-docsswaggerInput>
                    
                    <outputFile>src/docs/asciidoc/generated/alloutputFile>

                    

                    <config>
                        
                        <swagger2markup.markupLanguage>ASCIIDOCswagger2markup.markupLanguage>
                        

                        <swagger2markup.outputLanguage>ZHswagger2markup.outputLanguage>
                        <swagger2markup.generatedExamplesEnabled>trueswagger2markup.generatedExamplesEnabled>
                        <swagger2markup.inlineSchemaEnabled>falseswagger2markup.inlineSchemaEnabled>
                        <swagger2markup.pathsGroupedBy>TAGSswagger2markup.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

生成HTML文档

添加asciidoctor插件

<plugin>
                <groupId>org.asciidoctorgroupId>
                <artifactId>asciidoctor-maven-pluginartifactId>
                <version>1.5.6version>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generatedsourceDirectory>
                    <outputDirectory>src/docs/asciidoc/htmloutputDirectory>
                    <backend>html5backend>
                    <attributes>
                        
                        <toc>lefttoc>
                        
                        <toclevels>3toclevels>
                        
                        <sectnums>truesectnums>
                    attributes>
                configuration>
            plugin>

生成HTML文档

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

相关说明

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

生成PDF文档

添加asciidoctor插件

<plugin>
                <groupId>org.asciidoctorgroupId>
                <artifactId>asciidoctor-maven-pluginartifactId>
                <version>1.5.6version>
                <configuration>
                  <sourceDirectory>src/docs/asciidoc/generatedsourceDirectory>
                    <outputDirectory>src/docs/asciidoc/pdfoutputDirectory>
                    <backend>pdfbackend>
                configuration>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctorgroupId>
                        <artifactId>asciidoctorj-pdfartifactId>
                        <version>1.5.0-alpha.16version>
                    dependency>
                dependencies>
            plugin>

生成PDF文档

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

解决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.asciidoctorgroupId>
                <artifactId>asciidoctor-maven-pluginartifactId>
                <version>1.5.6version>
                <configuration>
                  <sourceDirectory>src/docs/asciidoc/generatedsourceDirectory>
                configuration>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctorgroupId>
                        <artifactId>asciidoctorj-pdfartifactId>
                        <version>1.5.0-alpha.16version>
                    dependency>
                dependencies>
                <executions>
                    <execution>
                        <id>output-htmlid>
                        <phase>generate-resourcesphase>
                        <goals>
                            <goal>process-asciidocgoal>
                        goals>
                        <configuration>
                            <backend>html5backend>
                       <outputDirectory>src/docs/asciidoc/htmloutputDirectory>
                            <attributes>
                                
                                <toc>lefttoc>
                                
                                <toclevels>3toclevels>
                                
                                <sectnums>truesectnums>
                            attributes>
                        configuration>
                    execution>
                    <execution>
                        <id>output-pdfid>
                        <phase>generate-resourcesphase>
                        <goals>
                            <goal>process-asciidocgoal>
                        goals>
                        <configuration>
                            <backend>pdfbackend>
                        <outputDirectory>src/docs/asciidoc/pdfoutputDirectory>
                        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问题解决

相关说明

• executions：多个执行任务配置
• execution.id：不可重复
• 其他：参考单独生成HTML与PDF相关说明

项目版本说明：

• spring boot 2.0.x
• swagger 2.8.0

文章参考

https://www.twblogs.net/a/5cc469a9bd9eee3aed78f106/zh-cn
https://blog.csdn.net/qq_22211217/article/details/97301464
还有一个找不到了