Swagger转PDF转HTML

最新推荐文章于 2024-03-23 23:36:08 发布
最新推荐文章于 2024-03-23 23:36:08 发布
阅读量824 收藏
点赞数
分类专栏： java SpringBoot Swagger 文章标签： swagger java springboot
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/tian6318/article/details/100062449
版权
java 同时被 3 个专栏收录
8 篇文章 0 订阅
订阅专栏
SpringBoot
3 篇文章 0 订阅
订阅专栏
Swagger
2 篇文章 0 订阅
订阅专栏

看了不少Swagger 转PDF的文章，很多不能很好的跑起来，或多或少有点问题，并对PDF中文问题进行了处理，所以自己总结，写个总结，做个示例

本文参考了：
http://swagger2markup.github.io/swagger2markup/1.3.1/
https://github.com/Swagger2Markup/spring-swagger2markup-demo

Swagger 转PDF 的背景：
Swagger 是一个强大的API文档工具，但是在实际使用中会碰到一个比较现实的问题，

  1. 你开发好了一个接口，但是项目环境隔离，导致接口调用方访问不到Swagger，但是人家却等着开发
  2. 上个版本的迭代，依然在接续，但是，新的版本已经开始，人家看不到新版的Swagger
    但是，重新编写 接口文档，又费时费力，所以就需要Swagger 生成静态文档

技术重点：

  1. swagger2markup JSON转成对应格式的文本文件，支持有asciidoc，markdown，confluence
  2. asciidoctorj ，将对应的文本文件转为 HTML
  3. 项目架构为 JDK1.8 maven springboot

示例代码：
1·pom 文件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.1.7.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.cloud</groupId>
	<artifactId>swagger-converter</artifactId>
	<version>1.0.0</version>
	<name>swagger-converter</name>
	<description>swagger-converter</description>

	<properties>
		<maven-jar-plugin.version>3.1.1</maven-jar-plugin.version>
		<!-- java version -->
		<java.version>1.8</java.version>
		
		<!-- swagger2markup config -->
		<swagger2markup.version>1.3.3</swagger2markup.version>
		<!-- 输出语言类型ASCIIDOC(".adoc,.asciidoc"),MARKDOWN(".md,.markdown"),CONFLUENCE_MARKUP(".txt") -->
		<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
		<swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
		<!-- AS_IS,TAGS,REGEX  -->
		<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
		
		<!-- asciidoctor config -->
        <asciidoctor.input.directory>${project.basedir}/src/docs/generated</asciidoctor.input.directory>
		<asciidoctor.font>${project.basedir}/src/main/resources/fonts</asciidoctor.font>
		<asciidoctor.themes>${project.basedir}/src/main/resources/themes</asciidoctor.themes>
		
		<!-- swagger config -->
		<!-- swagger JSON 数据地址 -->
		<swagger.input>http://127.0.0.1:8080/v2/api-docs?group=%E7%94%A8%E6%88%B7%E7%9B%B8%E5%85%B3%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3</swagger.input>
        <swagger.output.dir>${project.basedir}/src/docs/swagger</swagger.output.dir>
        <swagger.snippetOutput.dir>${project.basedir}/src/docs/snippets</swagger.snippetOutput.dir>
        <generated.asciidoc.directory>${project.basedir}/src/docs/generated</generated.asciidoc.directory>
        <asciidoctor.html.output.directory>${project.basedir}/src/docs/html</asciidoctor.html.output.directory>
        <asciidoctor.pdf.output.directory>${project.basedir}/src/docs/pdf</asciidoctor.pdf.output.directory>

        <jackson.version>2.9.6</jackson.version>
        <springfox.version>2.9.2</springfox.version>
	</properties>

	<dependencies>
		<dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.20</version>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>26.0-jre</version>
        </dependency>
        <dependency>
            <groupId>net.logstash.logback</groupId>
            <artifactId>logstash-logback-encoder</artifactId>
            <version>5.1</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.dataformat</groupId>
            <artifactId>jackson-dataformat-smile</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.module</groupId>
            <artifactId>jackson-module-afterburner</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-staticdocs</artifactId>
            <version>2.6.1</version>
            <exclusions>
            	<exclusion>
            		<groupId>io.github.robwin</groupId>
            		<artifactId>swagger2markup</artifactId>
            	</exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.module</groupId>
            <artifactId>jackson-module-jsonSchema</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        <dependency>
            <groupId>io.github.robwin</groupId>
            <artifactId>assertj-swagger</artifactId>
            <version>0.8.1</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>${swagger2markup.version}</version>
        </dependency>
        <dependency>
		    <groupId>io.github.swagger2markup</groupId>
		    <artifactId>swagger2markup</artifactId>
		    <version>${swagger2markup.version}</version>
		</dependency>
		<dependency>
		    <groupId>org.asciidoctor</groupId>
		    <artifactId>asciidoctorj</artifactId>
		    <version>2.1.0</version>
		</dependency>
	</dependencies>

	<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>${swagger2markup.markupLanguage}</swagger2markup.markupLanguage>
                        <swagger2markup.pathsGroupedBy>${swagger2markup.pathsGroupedBy}</swagger2markup.pathsGroupedBy>
                        <swagger2markup.outputLanguage>${swagger2markup.outputLanguage}</swagger2markup.outputLanguage>
                        <swagger2markup.extensions.dynamicOverview.contentPath>${generated.asciidoc.directory}</swagger2markup.extensions.dynamicOverview.contentPath>
                        <swagger2markup.extensions.dynamicDefinitions.contentPath>${generated.asciidoc.directory}</swagger2markup.extensions.dynamicDefinitions.contentPath>
                        <swagger2markup.extensions.dynamicPaths.contentPath>${generated.asciidoc.directory}</swagger2markup.extensions.dynamicPaths.contentPath>
                        <swagger2markup.extensions.dynamicSecurity.contentPath>${generated.asciidoc.directory}</swagger2markup.extensions.dynamicSecurity.contentPath>
                        <swagger2markup.extensions.springRestDocs.snippetBaseUri>${generated.asciidoc.directory}</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>
                            <attributes>
	                        	<pdf-fontsdir>${asciidoctor.font}</pdf-fontsdir>
	                            <pdf-stylesdir>${asciidoctor.themes}</pdf-stylesdir>
	                            <pdf-style>cn</pdf-style>
	                        </attributes>
                        </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>
                            <mainClass>io.github.robwin.swagger2markup.petstore.Application</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>
</project>

其中：

swagger.input：为在线swagger JSON字符串，可为文件也可以是在线接口请求
asciidoctor.pdf.output.directory：pdf 输出地址
asciidoctor.html.output.directory：html 输出地址
generated.asciidoc.directory：swagger 中间文件保存地址
asciidoctor.font ：字体地址
asciidoctor.themes ：主题地址

  1. 获取 swagger 数据地址，最直接的方式：
    在这里插入图片描述
    复制出完整路径， 替换 swagger.input 即可

  2. 执行 mvn clean test 即可生成对应的PDF接口文档

  3. 生成的样式为：
    pdf:在这里插入图片描述
    html:
    在这里插入图片描述

  4. 很多时候，公司会搭建 markdown，confluence 文档服务器，所以我们怎么可以生成对应的文档呢

  5. 生成 AsciiDocs

			//输出Ascii格式
	        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
	        		.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
	                .withOutputLanguage(Language.ZH)
	                .withPathsGroupedBy(GroupBy.TAGS)
	                .withGeneratedExamples()
	                .withoutInlineSchema()
	                .withBasePathPrefix()
	                .withListDelimiter()
	                .build();
	        
	        Swagger2MarkupConverter.from(new URL(API_URL))
	                .withConfig(config)
	                .build()
	                .toFile(Paths.get(PATH));
  1. 生成Confluence
			//生成Markdown格式文档
	        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
	                .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
	                .withOutputLanguage(Language.ZH)
	                .withPathsGroupedBy(GroupBy.TAGS)
	                .withGeneratedExamples()
	                .withoutInlineSchema()
	                .withBasePathPrefix()
	                .withListDelimiter()
	                .build();
	        
	        Swagger2MarkupConverter.from(new URL(API_URL))
	                .withConfig(config)
	                .build()
	                .toFile(Paths.get(PATH));
  1. 生成 MarkdownDocs
			//生成Markdown格式文档
	        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
	                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
	                .withOutputLanguage(Language.ZH)
	                .withPathsGroupedBy(GroupBy.TAGS)
	                .withGeneratedExamples()
	                .withoutInlineSchema()
	                .withBasePathPrefix()
	                .withListDelimiter()
	                .build();
	        
	        Swagger2MarkupConverter.from(new URL(API_URL))
	                .withConfig(config)
	                .build()
	                .toFolder(Paths.get(PATH));

示例DEMO，稍后放出

上海程序员-紫枫
关注
专栏目录
swagger文档转html
Cecil_X的专栏
08-03 906
swagger文档在开发时是一个很大的助力，但是在对外提供接口文档时就不是很灵活。 这里记录一下从swagger文档转html的方法(还能转pdf，暂时用不上)。 先建立一个空的maven项目，在pom中添加 <properties> <maven.compiler.source>8</maven.compiler.source> <maven.compiler.target>8</maven.compil
swagger导出pdf和html
11-14
swagger导出pdf和html。
swagger导出到pdf、html文档
热门推荐
北回归线的博客
01-27 1万+
swagger导出pdf, work, html接口文档
swagger生成PDF
leveretz的博客
11-25 504
swagger生成PDF
swagger生成pdf文档
cwb521zg的专栏
06-01 173
<dependencies> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.1</version> </dependency>...
Swagger转PDF转HTML示例代码
08-25
总的来说，Swagger转PDF转HTML是一个实用的功能，它可以帮助开发者更好地管理和分享他们的API文档。使用Java和相关的工具，你可以轻松实现这一目标，提高团队协作的效率。在实际操作中，确保遵循最佳实践，如保持...
swagger文档离线导出,word、pdf、html
01-19
Swagger 文档可以导出为多种格式，包括 Word（.docx）、PDF、HTML、SVG 和 XML。这些格式各有其用途： 1. **Word (DOCX)**：适合编辑和打印，便于在组织内部进行评审和协作。Word 文件可以方便地添加批注、修改和...
swagger生成pdf
09-20
而将 Swagger 文档转换为 PDF、HTML 或 Word 格式，则可以帮助开发者、团队成员和用户更方便地查看和打印 API 文档。 在"swagger生成pdf,html,word完整示例代码"中，我们主要探讨如何将 Swagger 定义转换为不同格式...
Swagger文档PDF版
07-03
Swagger文档PDF版是关于如何在SpringBoot项目中集成Swagger并进行相关配置的指南。Swagger是一个流行的API框架，尤其适合在前后端分离的项目中使用，它可以帮助开发人员生成实时的RESTful API文档，并且允许在线测试...
使用插件将swagger文档转html或pdf
最新发布
libing__123的博客
03-23 1156
github上有maven开源插件swagger2markup将swagger文档转为.adoc格式的文档，另外一个maven开源插件asciidoctorj-pdf则可以将.adoc格式的文档转为html和pdf。由于GitHub访问不稳定，在gitee上有镜像项目。所以我就贴gitee上的项目地址了。实现从swagger文档转为html或pdf的项目有两个。一个一个说。
swagger生成html离线接口文档
04-15
swagger生成html离线接口文档swagger生成html离线接口文档
swagger-converter:将Swagger文档从1.2版转换为2.0版
05-10
Swagger转换器 将文档从1.x版本转换为2.0版本 安装 使用npm npm install swagger-converter --save 用法 建议使用或类的命令行工具来转换您的规范。 此模块将不处理验证，如果您的规范无效，则会产生无效的规范。 转换功能 convert accept接受以下参数： resourceListing （必需）是Swagger 1.x入口点文件。 apiDeclarations （必需）是一个映射，其中带有来自resourceListing路径作为键，而来自resourceListing值作为值 options （可选）-有关的完整列表，请参见选项 var swaggerConverter = require ( 'swagger-converter' ) ; var resourceListing = require ( '/path/to
spring-boot，swagger2，生成html及中文pdf示例
04-24
spring-boot，swagger2，生成html及中文pdf示例。 https://download.csdn.net/download/lihuaijun/10313631 asciidoctorj-pdf支持中文生成 这个资源的评论里，有人说运行出错，我把例子发上来
Swagger指南之从入门到精通.pdf
02-12
Swagger（丝袜哥） 给人第一印象就是【最（hen） 流（niu） 行（bai） 】 ，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。 Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。 现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。 2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在github。
Swagger UI Converter-crx插件
03-10
显示从Json / Yaml swagger文件到swagger UI的转换 在Github和Bitbucket v6.5上工作 显示并排显示UI扩展以扩展Yaml / Json文件的扩展。 适用于Github和Bitbucket。 支持语言:English
Swagger2导出Html和pdf文件
yangli_的博客
10-28 639
Swagger2导出Html和pdf文件
Swagger2生成在线接口文档并导出pdf文件
xunming的专栏
05-31 3861
1，配置 2，注解 3，切换主题 4，生成pdf文件，解决中文丢失 adoc-html-pdf github
Swagger导出PDF与HTML教程：Maven配置与操作详解
本文将详细介绍如何使用Swagger将API文档导出为PDF和HTML格式，以便更好地展示和分享给团队成员或外部用户。 首先，导出Swagger文档的基本步骤如下： 1. 添加Swagger导出配置： 在项目中，确保已集成Swagger，这...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值