Swagger导出文件

文章目录

Swagger导出文件
一，导出文档实现
二，中文乱码问题
三，多文件合并

通过引入springfox-swagger2和springfox-swagger-ui，我们已经可以通过swagger.html查看接口信息，但此时还不能导出PDF文档或HTML。

一，导出文档实现

1.1 环境搭建

在docs目录下，创建ascidoc目录

在ascidoc目录下，创建generated，html，pdf目录

提前准备好api-docs接口（我这边是 http://localhost:8959/v2/api-docs）

1.2 pom文件

	<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.7.0</version>
	</dependency>
	<!-- ********************* swagger导出PDF/HTML所需依赖 START ********************************* -->
	<dependency>
		<groupId>io.github.swagger2markup</groupId>
		<artifactId>swagger2markup</artifactId>
		<version>1.3.1</version>
	</dependency>
	<dependency>
		<groupId>ch.netzwerg</groupId>
		<artifactId>paleo-core</artifactId>
		<version>0.10.2</version>
	</dependency>
	<dependency>
		<groupId>io.vavr</groupId>
		<artifactId>vavr</artifactId>
		<version>0.9.2</version>
	</dependency>

	......

	<build>
			<!--此插件生成ASCIIDOC-->
			<plugin>
				<groupId>io.github.swagger2markup</groupId>
				<artifactId>swagger2markup-maven-plugin</artifactId>
				<version>1.2.0</version>
				<configuration>
					<!--此处端口一定要是当前项目启动所用的端口-->
					<swaggerInput>http://localhost:8959/v2/api-docs</swaggerInput>
					<outputDir>src/docs/asciidoc/generated</outputDir>
					<config>
						<!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
						<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
					</config>
				</configuration>
			</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.10.1</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>src/docs/asciidoc/generated</sourceDirectory>
					<sourceHighlighter>coderay</sourceHighlighter>
					<attributes>
						<toc>left</toc>
					</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>generate-resources</phase>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>html5</backend>
							<outputDirectory>src/docs/asciidoc/html</outputDirectory>
						</configuration>
					</execution>

					<execution>
						<id>output-pdf</id>
						<phase>generate-resources</phase>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>pdf</backend>
							<outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
						</configuration>
					</execution>

				</executions>
			</plugin>

		</plugins>
	</build>

1.3 导出文件

在应用目录下，先后执行以下命令

mvn clean compile
mvn swagger2markup:convertSwagger2markup
mvn generate-resources

然后在generated，html，pdf就已经生成相关文件（definitions.adoc/pdf/html，overview.adoc/pdf/html，paths.adoc/pdf/html，security.adoc/pdf/html）

二，中文乱码问题

通过以上操作可以导出HTML和PDF文件，但PDF文件中如果存在中文字符，那有可能会出现中文乱码的问题。此时我们需要配置字体来解决中文乱码。

访问 https://gitee.com/lmchh/lmc-tools/tree/master/tools-common/src/docs/asciidoc/generated ，复制fonts目录和themes目录到本地的generated，html，pdf三个目录下（我是一开始复制到PDF目录下，然后报错，结果三个目录都拷贝一份就没问题，也有可能只需要拷贝到generated目录而已，暂时没有去尝试）。然后修改pom文件的插件asciidoctor-maven-plugin

					<execution>
						<id>output-pdf</id>
						<phase>generate-resources</phase>
						<goals>
							<goal>process-asciidoc</goal>
						</goals>
						<configuration>
							<backend>pdf</backend>
							<outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
							<!--解决中文乱码以及中文丢失问题-->
							<attributes>
								<toc>left</toc>
								<toclevels>3</toclevels>
								<numbered></numbered>
								<hardbreaks></hardbreaks>
								<sectlinks></sectlinks>
								<sectanchors></sectanchors>
								<generated>src/docs/asciidoc</generated>
								<pdf-fontsdir>fonts</pdf-fontsdir>
								<pdf-stylesdir>themes</pdf-stylesdir>
								<pdf-style>cn</pdf-style>
							</attributes>
						</configuration>
					</execution>

此时，再重新通过以下命令，就可以导出正常的文件

mvn clean compile
mvn swagger2markup:convertSwagger2markup
mvn generate-resources

三，多文件合并

从前面的操作，我们知道，每次都会在目录下产生4个文件，分别代表接口，实体类等。如果我们只需要导出一个文件，那就需要将四个文件进行合并，需要修改插件swagger2markup-maven-plugin，修改outputDir为outputFile

			<!--此插件生成ASCIIDOC-->
			<plugin>
				<groupId>io.github.swagger2markup</groupId>
				<artifactId>swagger2markup-maven-plugin</artifactId>
				<version>1.2.0</version>
				<configuration>
					<!--此处端口一定要是当前项目启动所用的端口-->
					<swaggerInput>http://localhost:8959/v2/api-docs</swaggerInput>
				    <!-- <outputDir>src/docs/asciidoc/generated</outputDir> -->
					<outputFile>src/docs/asciidoc/generated/all</outputFile>
					<config>
						<!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
						<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
					</config>
				</configuration>
			</plugin>