# *springboot+swagger2生成离线Api文档*

最新推荐文章于 2021-08-15 16:09:17 发布
最新推荐文章于 2021-08-15 16:09:17 发布
阅读量411 收藏
点赞数
文章标签： spring spring boot java
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/kesheqqlsx/article/details/105975838
版权
本文档介绍了如何在Springboot项目中结合Swagger2，通过配置Maven依赖、插件以及编写测试类和Swagger配置，来生成离线的Api文档。详细步骤包括在指定目录创建index.adoc文件，并通过运行mvn clean test命令来完成文档的生成。
摘要由CSDN通过智能技术生成

**

springboot+swagger2生成离线Api文档

版本

springboot:2.2.6
idea:2019.1.3
jdk:1.8

Maven依赖引入

   <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>

        <swagger2markup.version>1.2.0</swagger2markup.version>
        <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory>
        <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
        <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>
        <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>
        <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
        <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
        <swagger.input>${swagger.output.dir}/swagger.json</swagger.input>
        <springfox.version>2.9.2</springfox.version>
    </properties>

    <repositories>
        <repository>
            <id>jcentral</id>
            <name>bintray</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--Default Log Encoder for Swagger2Markup-->
        <dependency>
            <groupId>net.logstash.logback</groupId>
            <artifactId>logstash-logback-encoder</artifactId>
            <version>5.1</version>
        </dependency>
        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <!--offline doc-->
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
            <!--<scope>test</scope>-->
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>${swagger2markup.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-staticdocs</artifactId>
            <version>2.6.1</version>
            <!--<scope>test</scope>-->
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

Maven插件

<pluginRepositories>
        <pluginRepository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
        </pluginRepository>
        <pluginRepository>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.3</version>
                <configuration>
                    <compilerVersion>${java.version}</compilerVersion>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                    <encoding>UTF-8</encoding>
                    <!-- prevents endPosTable exception for maven compile -->
                    <useIncrementalCompilation>false</useIncrementalCompilation>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <systemPropertyVariables>
                        <io.springfox.staticdocs.outputDir>${swagger.output.dir}</io.springfox.staticdocs.outputDir>
                        <io.springfox.staticdocs.snippetsOutputDir>${swagger.snippetOutput.dir}</io.springfox.staticdocs.snippetsOutputDir>
                    </systemPropertyVariables>
                </configuration>
            </plugin>

            <!-- First, use the swagger2markup plugin to generate asciidoc -->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>${swagger2markup.version}</version>
                <dependencies>
                    <dependency>
                        <groupId>io.github.swagger2markup</groupId>
                        <artifactId>swagger2markup-import-files-ext</artifactId>
                        <version>${swagger2markup.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>io.github.swagger2markup</groupId>
                        <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
                        <version>${swagger2markup.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <swaggerInput>${swagger.input}</swaggerInput>
                    <outputDir>${generated.asciidoc.directory}</outputDir>
                    <config>
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>

                        <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
                        <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
                        <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
                        <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath>

                        <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</swagger2markup.extensions.springRestDocs.snippetBaseUri>
                        <swagger2markup.extensions.springRestDocs.defaultSnippets>true</swagger2markup.extensions.springRestDocs.defaultSnippets>
                    </config>
                </configuration>
                <executions>
                    <execution>
                        <phase>test</phase>
                        <goals>
                            <goal>convertSwagger2markup</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <!-- Run the generated asciidoc through Asciidoctor to generate
                 other documentation types, such as PDFs or HTML5 -->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.16</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
                    <sourceDocumentName>index.adoc</sourceDocumentName>
                    <attributes>
                        <doctype>book</doctype>
                        <toc>left</toc>
                        <toclevels>3</toclevels>
                        <numbered></numbered>
                        <hardbreaks></hardbreaks>
                        <sectlinks></sectlinks>
                        <sectanchors></sectanchors>
                        <generated>${generated.asciidoc.directory}</generated>
                    </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>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

            <!-- specify the main class for the manifest -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.1.0</version>
                <configuration>
                    <archive>
                        <manifest>
                            <addClasspath>true</addClasspath>
                            <classpathPrefix>lib/</classpathPrefix>
                            <!--important!!! specify the main class for the manifest!!!-->
                            <mainClass>com.chinamobile.cmic.apidoc.ApiDocApplication</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>

            <!-- copy dependencies to the lib directory -->
            <plugin>
                <artifactId>maven-dependency-plugin</artifactId>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>copy-dependencies</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${project.build.directory}/lib</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

            <!-- copy the generated documents -->
            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.1.0</version>
                <executions>
                    <execution>
                        <id>copy-resources</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>copy-resources</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
                            <resources>
                                <resource>
                                    <directory>${asciidoctor.html.output.directory}</directory>
                                </resource>
                                <resource>
                                    <directory>${asciidoctor.pdf.output.directory}</directory>
                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

创建测试类

import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

import java.io.BufferedWriter;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

/**
 * @ClassName Swagger2MarkupTest
 * @Description TODO
 * @Author ksqq
 * @Date 2020/5/7 15:48
 * @Version 1.0
 **/
@WebAppConfiguration
@RunWith(SpringRunner.class)
@AutoConfigureRestDocs(outputDir = "build/asciidoc/snippets")
@SpringBootTest(classes = {SwaggertestApplication.class, com.kesheqq.swaggertest.SwaggerConfig.class})
@AutoConfigureMockMvc
public class Swagger2MarkupTest {

    @Autowired
    private MockMvc mockMvc;
    @Autowired
    private WebApplicationContext webApplicationContext;

    @Test
    public void createSpringfoxSwaggerJson() throws Exception {
        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andReturn();

        MockHttpServletResponse response = mvcResult.getResponse();
        String swaggerJson = response.getContentAsString();
        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {
            writer.write(swaggerJson);
        }
    }

    @Before
    public void before() {
        //获取mockmvc对象实例
        mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext).build();
    }
}

Swagger配置类

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.builders.PathSelectors.ant;

/**
 * @ClassName SwaggerConfig
 * @Description TODO
 * @Author ksqq
 * @Date 2020/5/7 15:51
 * @Version 1.0
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .paths(Predicates.and(ant("/**"), Predicates.not(ant("/error"))))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("TestAPI Document")
                .description("TestAPI Document for SpringBoot2.2.6 Project")
                .contact(new Contact("ksqq", "", ""))
                .version("1.0")
                .build();
    }
}

创建index.adoc

在src/docs/asciidoc/下创建index.adoc，内容如下

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

最后运行mvn clean test即可

kesheqqlsx
关注
  • 0
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
SwaggerOfflineDoc：基于SpringBoot和Swagger2生成离线文档：PDF和HTML5格式
02-05
SwaggerOfflineDoc 基于SpringBoot和Swagger2生成离线文档：PDF和HTML5格式具体参考： ://blog.csdn.net/fly910905/article/details/79131755
swagger2markup生成离线的API接口文档
阿啄debugIT
02-05 759
一、背景 swager2只能生成在线的接口文档，有时候我们需要pdf、word的文档。利用swagger2markup可以生成静态的html和pdf文档。 二、步骤 1. 添加swagger2的依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springf...
Swagger2构建离线RESTful API
orchidMantis的博客
11-08 179
Swagger2 生成 离线 PDF、HTML文档 用途：Swagger是一个简单但功能强大的API表达工具，使用Swagger生成API，我们可以得到交互式文档 集成：引入依赖，配置Swagger，设置静态资源映射 使用：@ApiOperation，@ApiImplicitParams，@ApiImplicitParam注解 若本篇文章有看不懂的地方可见上篇文章有详细讲解 配置pom....
springboot快速集成swagger2，支持离线文档导出
WoddenFish的博客
07-14 718
话不多说，直接上步骤！ 1、导入maven依赖，版本可以自己更换 <!--引入swagger相关jar包--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <de
【Java】Springboot 通过Swagger2插件自动生成API文档
aiguoguo000的博客
04-22 1595
第一次在Springboot中使用Swagger2来自动生成接口文档，先把在线API文档处理好后，再做离线静态API文档，这里做个记录： 一、生成在线API文档 1.pom.xml中依赖swagger2 <!-- 接口生成文档swagger2 --> <dependency> <groupId>io...
基于SpringBoot和Swagger2生成离线文档：PDF和Html5格式.zip
最新发布
04-08
标题中的“基于SpringBoot和Swagger2生成离线文档：PDF和Html5格式”是指使用SpringBoot框架和Swagger2工具来创建API文档，并将其导出为可供离线阅读的PDF和HTML5格式。这一过程涉及了几个关键的IT知识点： 1. **...
swagger生成html离线接口文档
04-15
这个“swagger生成html离线接口文档”的主题聚焦于如何使用Swagger来生成HTML格式的离线API文档，这对于那些需要在没有网络连接的环境中查阅API文档的开发者来说非常有用。 Swagger的核心组件是Swagger Spec（也...
将Swagger2文档导出为HTML或markdown等格式离线阅读解析
08-25
Swagger2文档导出为HTML或markdown格式离线阅读解析 Swagger2文档导出为HTML或markdown格式离线阅读是指将Swagger2文档导出为离线阅读的格式，以便在没有网络连接的情况下访问接口文档。本文将详细介绍将Swagger2...
springboot项目中json导出成标准接口文档到word（swagger样式）
06-29
根据业务需求需要，需要将json格式的api信息【比如postman导出接口文档这类的】，导出成标准接口文档的word文件。 该平台是将一些好的第三方平台接口接入进来，供用户使用，每个用户下有可以使用的接口，可以根据...
swagger2离线文档生成项目
01-15
用swagger2markup导出swagger2项目的html，pdf的离线文档。解决生成pdf中文乱码以及缺失的问题，支持自定义字体。 修改pom.xml中的 swagger.input属性值中的ip和port 执行mvn clean test完成之后，会在/target/asciidoc/pdf/目录下生成index.pdf，该pdf文件即是生成的swagger项目接口的文档。
springboot2.0版本中文文档
07-17
此pdf文件是springboot2.0版本的中文文档，希望可以帮助大家在技术上提升的更快
swagger 接口文档
08-26
本文整理了 spring boot + jpa+mysql+redis +swagger+yml等技术，实现了微服务restFul 风格的demo,下载即运行[http://localhost:8080/swagger-ui.html 进行文档展示] [http://localhost:8080/user/ma 访问接口]
使用springfox-staticdocs生成swagger离线api项目源码
04-06
使用springfox-staticdocs生成swagger离线api项目源码,只需要配置对应的url，既可生成离线的api文档。该项目的优势在于是一个独立的项目，不要集成到实际开发项目中。
SpringBoot2.1官方文档 完整版
11-09
SpringBoot2.1官方文档 十分详细
Spring boot集成swagger2生成接口文档的全过程
08-25
主要给大家介绍了关于Spring boot集成swagger2生成接口文档的相关资料，文中通过示例代码介绍的非常详细，对大家学习或者使用Spring boot具有一定的参考学习价值，需要的朋友们下面来一起学习学习吧
使用SpringBoot + Swagger生成Api离线文档
qq_31404603的博客
03-24 2497
请参照：https://www.jianshu.com/p/af7a6f29bf4f
Spring Boot 2.X(十五)：集成 Swagger2 开发 API 文档（在线+离线）
朝雾轻寒的博客
11-06 724
前言 相信很多后端开发在项目中都会碰到要写 api 文档，不管是给前端、移动端等提供更好的对接，还是以后为了以后交接方便，都会要求写 api 文档。 而手写 api 文档的话有诸多痛点： 文档更新的时候，需要再次发送给对接人 接口太对，手写文档很难管理 接口返回的结果不明确 不能直接在线测试接口，通常需要使用工具，如 postman 等 Swagger 就很好的解决了这个问题。 Swagger...
引入swagger2 api接口文档并实现离线文档
weixin_43975403的博客
08-15 3680
前言 本篇文章在于介绍swagger2工具来管理接口文档，knife4j美化，以及多种swagger在线文档导出离线文档包括html、pdf、markdown、word文档。 目的 程序引入swagger工具来管理接口文档。 导入工具 <!--引入swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>
swagger 导出离线文档_swagger生成离线文档记录（支持中文）
weixin_39932181的博客
12-20 737
本档中的附件需要到有道云笔记的分享中下载：https://note.youdao.com/ynoteshare1/index.html?id=78031789325c5a5a9926818bbfe9a22e&type=note一、IDE为idea，使用maven构建的spring-boot工程，swagger版本为2.7.0二、拷贝docs目录、fonts目录与themes目录到src目录...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值