spring+swagger2生成在线文档，以及离线pdf文档

最新推荐文章于 2021-08-15 16:13:31 发布

焱鋮

最新推荐文章于 2021-08-15 16:13:31 发布

阅读量1.7k

点赞数 2

分类专栏： swagger2 文章标签： spring+swagger2 swagger2离线pdf文档 swagger2在线文档

本文链接：https://blog.youkuaiyun.com/jincheng_921/article/details/89528119

版权

swagger2 专栏收录该内容

1 篇文章

订阅专栏

本文详细介绍如何使用Spring和Swagger2生成在线API文档，并通过Maven插件将文档转化为离线PDF格式，涵盖依赖配置、Java代码实现及解决中文显示问题。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

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>