spring+swagger2生成在線文檔，以及離線pdf文檔

maven依賴

<!-- swagger2 start -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger2 end -->

        <!-- swagger2markup 生成靜態文件 start-->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
        <!-- swagger2markup 生成靜態文件 end -->
    </dependencies>

swagger2配置文件

package com.jincheng.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author: jinCheng
 * @description: swagger2配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Value("${swagger.enable:true}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enableSwagger)
                .apiInfo(apiInfo())
                .select()
                // 此處換成自己項目的掃描包
                .apis(RequestHandlerSelectors.basePackage("com.jincheng"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("示例 APIs")
                .version("1.0")
                .build();
    }
}

java代碼生成asciidoc文件

package com.jincheng;

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import java.net.MalformedURLException;
import java.net.URL;
import java.nio.file.Paths;

/**
 * @author: jinCheng
 * @description: java代碼生成文檔
 */
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class Swagger2Tests {

    /**
     * 獲取項目在線swagger的json數據,8099,修改爲自己項目設置的
     */
    private String swagger_source_url = "http://localhost:8099/v2/api-docs";

    /**
     * 生成的asciidoc文件的存放目錄
     */
    private String asciidoc_dir = "src/main/resources/docs/asciidoc/generated";

    private String fileName = "all";

    /**
     * 生成AsciiDocs格式文檔
     *
     * @throws MalformedURLException
     */
    @Test
    public void generateAsciiDoc() throws MalformedURLException {
        // MarkupLanguage三種格式:ASCIIDOC,MARKDOWN,CONFLUENCE_MARKUP
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();

        Swagger2MarkupConverter.from(new URL(swagger_source_url))
                .withConfig(config)
                .build()
                .toFolder(Paths.get(asciidoc_dir));
    }

    /**
     * 生成AsciiDocs格式文檔,並彙總成一個文件
     *
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() throws Exception {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(swagger_source_url))
                .withConfig(config)
                .build()
                .toFile(Paths.get(asciidoc_dir + "/" + fileName));
    }
}

maven插件生成asciidoc

路徑配置

    <properties>
        <java.version>1.8</java.version>
        <!-- 獲取項目在線swagger的json數據,端口號8099,修改爲自己項目設置的 -->
        <swagger_source_url>http://localhost:8099/v2/api-docs</swagger_source_url>
        <!-- 生成的asciidoc文件的存放目錄 -->
        <asciidoc_output_directory>src/main/resources/docs/asciidoc/generated</asciidoc_output_directory>
        <!-- 生成的html文件的存放目錄 -->
        <html_output_directory>src/main/resources/docs/html/generated</html_output_directory>
        <!-- 生成的pdf文件的存放目錄 -->
        <pdf_output_directory>src/main/resources/docs/pdf/generated</pdf_output_directory>
    </properties>

maven插件

 <!-- 生成ASCIIDOC,且均爲單個文件 (除了ASCIIDOC之外，還有MARKDOWN和CONFLUENCE_MARKUP可選)  -->
            <!-- 此插件使用時,需啓動項目 控制檯:swagger2markup:convertSwagger2markup  -->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.1</version>
                <configuration>
                    <swaggerInput>${swagger_source_url}</swaggerInput>
                    <outputDir>${asciidoc_output_directory}</outputDir>
                    <config>
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>

maven插件生成離線pdf文檔

插件信息

<!-- 此插件生成HTML和PDF 讀取已有的asciidoc文件,並轉換爲HTML和PDF-->
            <!-- mvn asciidoctor:process-asciidoc  mvn generate-resources -->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>

                <!-- 生成pdf需要使用的依賴  -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <!-- 注意此版本 -->
                        <version>1.5.0-alpha-zh.16</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>

                <configuration>
                    <!-- 源文件地址 asciidoc 存放的位置-->
                    <sourceDirectory>${asciidoc_output_directory}</sourceDirectory>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <!--菜單欄在左邊-->
                        <toc>left</toc>
                        <!--多標題排列-->
                        <toclevels>3</toclevels>
                        <!--自動生成數字序號-->
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>

                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <!-- 生成的html存放位置 -->
                            <outputDirectory>${html_output_directory}</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <!-- 生成的pdf存放位置 -->
                            <outputDirectory>${pdf_output_directory}</outputDirectory>
                            <!-- 解決pdf中文缺字問題 -->
                            <attributes>
                                <pdf-style>cn</pdf-style>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

生成pdf中文缺字問題

下載jar

https://gitee.com/jincheng-921/asciidoctorj-pdf-jar.git

上傳到maven本地倉庫，私服

https://blog.csdn.net/jincheng_921/article/details/89504440

項目源碼

https://gitee.com/jincheng-921/spring_swagger2_demo.git
項目啓動後查看在線文檔 http://localhost:8099/swagger-ui.html