Swagger2生成离线 pdf、html 接口文档

最新推荐文章于 2024-06-20 16:22:10 发布
最新推荐文章于 2024-06-20 16:22:10 发布
阅读量2.3k 收藏 6
点赞数 3
分类专栏： 后台开发框架 文章标签： swagger springboot
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_43934607/article/details/103060022
版权

一.pom文件中的配置

1.属性值设置

	 <properties>
        <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>
    </properties>

    <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>

    <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>

2.依赖

		<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>
        
	  <!--offline doc-->
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
            <!--<version>2.0.2.RELEASE</version>-->
            <!--<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>

3.插件（直接拷贝 不用修改）

 <build>
        <plugins>
            <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.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled>

                        <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>

			<!--如果第一次运行报错xxx.xxx.xxx程序包不存在再加上下面的 否则不加-->
<!--
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                    <compilerArguments>
                    	<!-- C:\Java\jdk1.8.0_11\ 该为电脑的jdk安装目录-->
                        <bootclasspath>C:\Java\jdk1.8.0_11\jre\lib\rt.jar;C:\Java\jdk1.8.0_11\jre\lib\plugin.jar</bootclasspath>
                    </compilerArguments>
                </configuration>
            </plugin>
-->
        </plugins>
    </build>

二.配置类

/**
 * swagger的设置
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hfut.laboratory.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("后台url接口文档")
                        .description("详细信息......")
                        // 作者信息
                        .contact(new Contact("yzx", "https://blog.csdn.net/weixin_43934607", "1915321657@qq.com"))
                        .version("1.0")
                        .build());
    }
}

三.建立 src/docs/asciidoc/index.adoc

在这里插入图片描述

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

四.新建单元测试生成swagger.json

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.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;

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

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;

import org.springframework.restdocs.operation.preprocess.Preprocessors;

@WebAppConfiguration
@RunWith(SpringJUnit4ClassRunner.class)
@AutoConfigureRestDocs(outputDir = "build/asciidoc/snippets")
@SpringBootTest
@AutoConfigureMockMvc
public class Swagger2MarkupTest {

    @Autowired
    private MockMvc mockMvc;

    @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);
        }
    }
}
  • 运行该测试之后 可以看到target生成：
    在这里插入图片描述

五.执行命令：mvn test

  • 可以看到target生成了接口文档
    在这里插入图片描述
槑！
关注
  • 3
    点赞
  • 踩
  • 6
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
swagger生成html离线接口文档
04-15
swagger生成html离线接口文档swagger生成html离线接口文档
Spring boot 2.1.3+Swagger2.9.2+swagger2markup生成离线HTML和pdf接口文档
残影杀
04-23 2039
Swagger2.9.2生成离线HTML接口文档 因为Swagger版本升级，导致以前的离线HTML接口文档无法使用，因此用了两天时间，重新研究。 1、接口文档展示 先展示一张最终效果图： 2、目的 配置到Springboot项目中以后，在项目打包的时候便会通过单元测试在指定的目录生成被官方称为staticdocs的离线文档 3、开始配置 1、Maven依...
swagger生成pdf接口文档操作流程
最新发布
weixin_39565734的博客
06-20 829
创建一个项目后，选择**“项目设置->导入数据->OpenAPI/Swagger->文件导入”**，将上一个步骤已导出的 Swagger 格式的 JSON 文件导入即可。是一个比 Postman 更强大的接口测试工具，Apifox = Postman + Swagger + Mock + JMeter，在开发完接口后，可以通过 Apifox 的 IDEA 插件一键生成接口文档，多端同步，非常方便测试和维护。开源项目，点击 swagger.json 文件，鼠标右键，将其存到电脑本地，如下图所示。
swagger2离线文档生成项目
01-15
用swagger2markup导出swagger2项目的html，pdf的离线文档。解决生成pdf中文乱码以及缺失的问题，支持自定义字体。 修改pom.xml中的 swagger.input属性值中的ip和port 执行mvn clean test完成之后，会在/target/asciidoc/pdf/目录下生成index.pdf，该pdf文件即是生成的swagger项目接口的文档。
swagger2的使用和swagger2markup离线文档的生成
很多时候犯错都是在不知情的情况下发生的
05-29 494
结合swagger2markup生成离线文档PDF/HTML格式 最常用的就是swagger2markup，即利用swagger.json生成asciidoc文档，然后转为html，pdf格式的文档。但是配置有些繁琐，所以就想可不可以利用一个demo工程直接访问现有项目的swagger接口来生成离线文档，这样就不会在当前项目引入额外的代码与配置。 demo工程地址为https://github.com/spiritn/spring-swagger2markup-demo.git...
Swagger2生成离线文档markdown、html以及pdf格式
weixin_45541084的博客
05-11 1435
Swagger2生成离线文档markdown、html以及pdf格式 第一次写文章，不喜勿喷，谢谢 实现离线文档我们只需要三板斧 1. 第一板斧:导入依赖 <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-ui</artifactId> <version>2.0.3</vers
swagger2生成html、pdf格式离线文档
07-15
在 Swagger2 中生成 HTML 和 PDF 格式的离线文档，我们可以利用 Maven 插件 Asciidoctor-Maven-Plugin 来实现。Asciidoctor 是一个快速、开源的文本处理器，它能够将 AsciiDoc 文档转换为 HTML、PDF 等多种格式。...
swagger文档离线导出,word、pdf、html
01-19
Swagger 是一个广泛使用的 API 设计和文档工具，它允许开发者以结构化的方式定义 RESTful API，使得服务接口清晰易懂，同时提供了一种交互式的 API 文档系统，方便开发者测试和理解 API 功能。Swagger 文档离线导出...
SwaggerOfflineDoc：基于SpringBoot和Swagger2生成离线文档：PDF和HTML5格式
02-05
SwaggerOfflineDoc基于SpringBoot和Swagger2生成离线文档：PDF和HTML5格式具体参考： ://blog.csdn.net/fly910905/article/details/79131755
基于SpringBoot和Swagger2生成离线文档：PDF和Html5格式.zip
02-12
标题中的“基于SpringBoot和Swagger2生成离线文档：PDF和Html5格式”指的是使用SpringBoot框架集成Swagger2工具来创建API文档，并进一步将其转换为离线可用的PDF和HTML5格式。这是一个常见且实用的方法，让开发者...
Swagger2离线文档：PDF和Html5格式
热门推荐
琦彦
01-22 5万+
Swagger2在线文档 http://blog.csdn.net/fly910905/article/details/79006747 Swagger2离线文档 0.程序结构 项目源码-Swagger2离线文档：PDF和Html5格式 1.Maven配置 <?xml version="1.0" encoding="UTF-8"?> <projec...
Swagger2离线文档：swagger2markup代码和插件方式
01-21
目录 Swagger文章汇总 Swagger2Markup简介 项目版本说明： swagger2markup代码方式 第一步：编辑pom.xml增加需要使用的相关依赖和仓库 第二步：编写一个单元测试用例来生成执行生成文档的代码 生成AsciiDoc 生成markdown 生成confluence swagger2markup插件方式 生成asciidoc或markdown文档 添加swagger2markup插件 生成asciidoc或markdown文档 相关说明 生成HTML文档 添加asciidoctor插件 生成HTML文档 生成PDF文档 添加asciidoctor插件 生成PDF文
spring-boot，swagger2，生成html及中文pdf示例
04-24
spring-boot，swagger2，生成html及中文pdf示例。 https://download.csdn.net/download/lihuaijun/10313631 asciidoctorj-pdf支持中文生成 这个资源的评论里，有人说运行出错，我把例子发上来
使用swagger2markup生成漂亮的PDF和HTML文档(完整工程，解压即用）
03-13
最近开发时需要用swagger生成文档，经多次测试，形成了一个完整的生成方案，供大家参考。可以在生成的文档中处定义章节。完整调试，保证可用。 工程后，操作步聚如下： 1、修改生成最终文档的索引文件index.adoc，在src/docs/asciidoc目录中，根据自己需要添加章节 2、修改pom.xml的30行地址，改为需要生成文档的系统地址 3、使用命令：mvn clean test 生成接口手册文档 4、生成的的文档路径如下： target\asciidoc\html target\asciidoc\pdf
Swagger的离线文档自动生成
aman801004的博客
07-21 1812
Swagger的离线文档 一、引言 众所周知，Swagger需要在微服务运行的时候才能查看文档，那么在开发过程中，由于频繁地调试项目，Swagger文档将处于几乎无法使用的情况。那么使用如何离线文档呢？ 二、离线文档的选型 1、Swagger2Markup：这是一个开源项目，项目的主页为： https://github.com/Swagger2Markup/swagger2markup 具体用法可参照： https://cloud.tencent.com/developer/article/1332445
引入swagger2 api接口文档并实现离线文档
weixin_43975403的博客
08-15 3651
前言 本篇文章在于介绍swagger2工具来管理接口文档，knife4j美化，以及多种swagger在线文档导出离线文档包括html、pdf、markdown、word文档。 目的 程序引入swagger工具来管理接口文档。 导入工具 <!--引入swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>
Swagger2 一键生成离线文档PDF
MapleStory11的博客
01-05 1235
Swagger 目前是大家常用的api管理工具，不过swagger官方并没有提供生成离线文档的接口。当需要生成离线文档时，该怎么办呢？ 可以使用下面这个工具： www.huurryy.com, 将swagger json 输入后，点击生成即可生成pdf 文档。非常方便。 ...
swagger 导出离线文档_swagger生成离线文档记录（支持中文）
weixin_39932181的博客
12-20 722
本档中的附件需要到有道云笔记的分享中下载：https://note.youdao.com/ynoteshare1/index.html?id=78031789325c5a5a9926818bbfe9a22e&type=note一、IDE为idea，使用maven构建的spring-boot工程，swagger版本为2.7.0二、拷贝docs目录、fonts目录与themes目录到src目录...
最简单的办法导出swagger的离线文档pdf，word，html
weixin_45676738的博客
11-16 2560
导入jar包 注意swagger 版本在小于等于2.6会报错。swagger2markup不兼容 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </d
swagger2生成离线文档
08-30
Swagger2是一个开源的项目，用于生成RESTful API的文档。通过Swagger2，我们可以方便地定义API的请求和响应格式、参数、返回值等，并且生成美观、易于阅读的文档。Swagger2支持在线文档生成，但在某些场景下，我们可能需要生成离线文档以便于查阅。 生成Swagger2的离线文档可以通过以下几个步骤实现： 1. 在项目中添加Swagger2的依赖。我们可以通过Maven或Gradle等工具，在项目的配置文件中添加Swagger2的依赖项，以便于能够在项目中使用Swagger2的相关注解和配置。 2. 在代码中添加Swagger2的注解。在需要生成文档的API接口的方法上，使用Swagger2提供的注解，如@Api、@ApiOperation、@ApiParam等，对API进行描述和参数的定义。 3. 配置Swagger2的参数。在项目的配置文件中，我们可以配置Swagger2的相关参数，如API文档的标题、描述、版本号等。我们还可以指定生成离线文档的输出路径。 4. 运行项目生成离线文档。启动项目后，访问Swagger2的API文档页面，可以查看在线文档。在该页面上，我们可以找到一个生成离线文档的按钮或链接，点击后会将API文档以HTML或其他格式导出到本地的指定路径。 通过以上步骤，我们就可以很方便地生成Swagger2的离线文档。在项目构建或发布过程中，我们可以将这些离线文档打包发布，供其他团队成员或API使用者参考和查阅。这样可以提高API的可理解性和使用性，减少沟通和解释成本，提升开发效率。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值