swagger+springboot 工程配置、导出html、adoc、pdf文档全过程记录。

最新推荐文章于 2022-11-21 16:38:15 发布

摸鱼的图图

最新推荐文章于 2022-11-21 16:38:15 发布

阅读量1.3k

点赞数 2

分类专栏： java 文章标签： maven java spring boot

本文链接：https://blog.csdn.net/qq_25529689/article/details/120437663

版权

java 专栏收录该内容

4 篇文章 1 订阅

订阅专栏

1.pom添加依赖jar包。

2.pom添加导出html、adoc、pdf的插件。

1.pom添加依赖jar包。

 <!--swagger相关-->
        <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>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.5</version>
        </dependency>

2.pom添加导出html、adoc、pdf的插件。

主要添加的是swagger2markup-maven-plugin和asciidoctor-maven-plugin两个插件。

2.1 swagger2markup-maven-plugin

用来生成adoc文件，其中要保证接口可访问，http://localhost:8080/v2/api-docs ，ip可换成自己的。如下图可看到json数据。

2.2 asciidoctor-maven-plugin

用来将生成的adoc文件转成pdf和html。其中所需要的字体（fonts）和主题(themes)及index.adoc会在下面标题3中介绍。

 <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.1</version>
                <configuration>
                   <!-- api-docs访问url -->
                    <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
                    <!--生成多个文件的路径 -->
                   <outputDir>src/main/doc/asciidoc/generated</outputDir>
                    <config>
                        <!--ascii格式文档-->                       <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    </config>
                </configuration>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>convertSwagger2markup</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

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

                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.11</version>
                    </dependency>
                    <!-- Comment this section to use the default jruby artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>9.1.8.0</version>
                    </dependency>
                    <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj</artifactId>
                        <version>1.5.4</version>
                    </dependency>
                </dependencies>

                <!-- Configure generic document generation settings -->
                <configuration>
                    <!--默认指向 ${basedir}/src/main/asciidoc-->
                    <sourceDirectory>src/main/doc</sourceDirectory>
                    <!--an override to process a single source file; 默认指向 ${sourceDirectory} 中的所有文件-->
                    <sourceDocumentName>index.adoc</sourceDocumentName>
                    <attributes>
                        <doctype>book</doctype>
                        <toc>left</toc>
                        <toclevels>3</toclevels>
                        <numbered></numbered>
                        <hardbreaks></hardbreaks>
                        <sectlinks></sectlinks>
                        <sectanchors></sectanchors>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>package</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>src/main/doc/asciidoc/html</outputDirectory>
                            <sourceHighlighter>coderay</sourceHighlighter>
                        </configuration>
                    </execution>
                    <execution>
                        <id>output-pdf</id>
                        <phase>package</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>src/main/doc/asciidoc/pdf</outputDirectory>
                            <sourceHighlighter>coderay</sourceHighlighter>
                            <doctype>book</doctype>
                            <attributes>
                                <toc>left</toc>
                                <toclevels>3</toclevels>
                                <numbered></numbered>
                                <hardbreaks></hardbreaks>
                                <sectlinks></sectlinks>
                                <sectanchors></sectanchors>
                                <pdf-fontsdir>./fonts</pdf-fontsdir>
                                <pdf-stylesdir>./themes</pdf-stylesdir>
                                <pdf-style>cn</pdf-style>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

3.工程添加字体和汉化的文件。

字体和主题下载地址：Releases · chloerei/asciidoctor-pdf-cjk-kai_gen_gothic · GitHub

将下载的所有文件放到fonts包，将压缩包zip或者tag.gz包解压后找到asciidoctor-pdf-cjk-kai_gen_gothic-0.1.0-fonts\data\themes下所有文件放到themes包。

添加index.adoc文件，内容如下：

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

4.工程添加配置文件。

4.1 添加swagger配置类

package com.config;

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.service.Contact;
import springfox.documentation.service.Tag;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //apiInfo指定测试文档基本信息，这部分将在页面展示
                .apiInfo(apiInfo())
               // .tags(new Tag("product", "产品接口"),getTags())
                .select()
                //apis() 控制哪些接口暴露给swagger，
                // RequestHandlerSelectors.any() 所有都暴露
                // RequestHandlerSelectors.basePackage("com.info.*")  指定包位置
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    //基本信息，页面展示
   private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("工程接口")
                .description("接口描述")
                //联系人实体类
                .contact(
                        new Contact("lll", "http://localhost:8080/swagger-ui.html", "kkk")
                )
                //版本号
                .version("0.0.1-SNAPSHOT")
                .build();
    }

    private Tag[] getTags() {
        Tag[] tags = {
                new Tag("user", "用户接口"),
                new Tag("api_product", "产品内部接口")
        };
        return tags;
    }

}

4.2 启动类中添加注解

4.3 Controller添加注解

5. 启动工程，浏览器查看

5.1 地址：http://localhost:8080/swagger-ui.html#/ 查看当前工程ui，也可进行测试。

5.2 地址：http://localhost:8080/doc.html 查看文档页面。

6. 执行命令生成文档。

启动工程后，在工程根目录下执行两个命令，第一个命令是mvn swagger2markup:convertSwagger2markup 生成adoc文件

第二个命令：mvn -DskipTests package 将生成的adoc文档转换成pdf和html

文档生成后是这样的：

目录如下图所示：

摸鱼的图图

关注

2
点赞
踩
1

收藏

觉得还不错? 一键收藏
2
评论
swagger+springboot 工程配置、导出html、adoc、pdf文档全过程记录。

目录1.pom添加依赖jar包。2.pom添加导出html、adoc、pdf的插件。3.工程添加字体和汉化的文件。4.工程添加配置文件。5. 启动工程，浏览器查看6. 执行命令生成文档。1.pom添加依赖jar包。  <dependency> <groupId>io.springfox</groupId> <artifa..
复制链接

扫一扫