swagger生成PDF接口文档

作者: 曜_CRY | 来源:发表于2019-07-14 10:51 被阅读0次

swagger生成PDF接口文档
[java]62、Swagger
怎么管理接口文档
记一次自定义拦截器失效的问题排查
Swagger代码实战
SpringBoot+Swagger+日志
怎么在springboot项目中使用swagger-spring
Swagger生成接口文档
swagger生成html文档
源码剖析@ApiImplicitParam对@RequestPa

1.在项目的的pom文件中引入依赖和插件

pom.xml

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

<id>jcenter</id>

<name>jcenter maven</name>

<url>http://jcenter.bintray.com</url>

</pluginRepository>

</pluginRepositories>

<swagger2markup.version>1.2.0</swagger2markup.version>

<asciidoctor.input.directory>${project.basedir}/src/main/asciidoc</asciidoctor.input.directory>

<swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>

<swagger.snippetOutput.dir>${project.build.directory}/generated-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>

<id>jcenter-snapshots</id>

<name>jcenter</name>

<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>

</repository>

</repositories>

<artifactId>ecss_swagger_starter</artifactId>

<version>0.0.2-RELEASE</version>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>${springfox-version}</version>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>${springfox-version}</version>

</dependency>

<groupId>org.springframework.restdocs</groupId>

<artifactId>spring-restdocs-mockmvc</artifactId>

<version>2.0.1.RELEASE</version>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-data-rest</artifactId>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-bean-validators</artifactId>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-staticdocs</artifactId>

</dependency>

<groupId>io.github.robwin</groupId>

<artifactId>assertj-swagger</artifactId>

</dependency>

</dependencies>

<groupId>org.springframework.cloud</groupId>

<artifactId>spring-cloud-dependencies</artifactId>

<version>${spring-cloud.version}</version>

<scope>import</scope>

</dependency>

</dependencies>

</dependencyManagement>

<build>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-surefire-plugin</artifactId>

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

<groupId>io.github.swagger2markup</groupId>

<artifactId>swagger2markup-maven-plugin</artifactId>

<version>${swagger2markup.version}</version>

<groupId>io.github.swagger2markup</groupId>

<artifactId>swagger2markup-import-files-ext</artifactId>

<version>${swagger2markup.version}</version>

</dependency>

<groupId>io.github.swagger2markup</groupId>

<artifactId>swagger2markup-spring-restdocs-ext</artifactId>

<version>${swagger2markup.version}</version>

</dependency>

</dependencies>

<swaggerInput>${swagger.input}</swaggerInput>

<outputDir>${generated.asciidoc.directory}</outputDir>

<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>

<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>

<swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/main/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>

<swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/main/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>

<swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/main/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>

<swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/main/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>

<goals>

<goal>convertSwagger2markup</goal>

</goals>

</execution>

</executions>

</plugin>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctor-maven-plugin</artifactId>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctorj-pdf</artifactId>

<version>1.5.0-alpha.10.1</version>

</dependency>

<groupId>org.jruby</groupId>

<artifactId>jruby-complete</artifactId>

</dependency>

</dependencies>

<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>

<sourceDocumentName>index.adoc</sourceDocumentName>

<generated>${generated.asciidoc.directory}</generated>

</attributes>

</configuration>

<!-- Since each execution can only handle one backend, run

separate executions for each desired output type -->

<id>output-html</id>

<goals>

<goal>process-asciidoc</goal>

</goals>

<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>

</configuration>

</execution>

<id>output-pdf</id>

<goals>

<goal>process-asciidoc</goal>

</goals>

<outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>

</configuration>

</execution>

</executions>

</plugin>

</plugins>

</build>

</project>

2.在项目的test目录中加入两个java类文件，加入后运行一次SwaggerTest.java，为了生成swagger.json，可到项目目录target\swagger中查看是否生成了swagger.json。

ControllerTest.java

package com.jet.ecss.contact.support;

import org.junit.Before;

import org.junit.Rule;

import org.junit.runner.RunWith;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;

import org.springframework.boot.test.context.SpringBootTest;

import org.springframework.restdocs.JUnitRestDocumentation;

import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;

import org.springframework.test.context.junit4.SpringRunner;

import org.springframework.test.web.servlet.MockMvc;

import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import org.springframework.web.context.WebApplicationContext;

@SpringBootTest

@RunWith(SpringRunner.class)

@AutoConfigureMockMvc

public abstract class ControllerTest {

protected MockMvc mockMvc;

@Autowired

protected WebApplicationContext context;

@Rule

public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();

@Before

public void setUp() {

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)

.apply(MockMvcRestDocumentation.documentationConfiguration(this.restDocumentation))

.build();

}

SwaggerTest.java

package com.jet.ecss.contact.support;

import org.junit.Test;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import org.springframework.http.MediaType;

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;

public class SwaggerTest extends ControllerTest {

private final static Logger logger = LoggerFactory.getLogger(SwaggerTest.class);

@Test

public void createSwaggerJson() throws Exception {

logger.info("------ 获取用于生成自动文档的swagger.json文件 ------");

String swaggerJson = this.mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))

.andExpect(status().isOk()).andReturn().getResponse().getContentAsString();

// 对应pom.xml中 <systemPropertyVariables> 设置的属性值

// String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");

String outputDir = "target/swagger";

Files.createDirectories(Paths.get(outputDir));

try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {

writer.write(swaggerJson);

}

return;

}

3.在项目main目录新建目录asciidoc，在里面新建一个index.adoc文件，文件内容如下

include::{generated}/overview.adoc[]

include::{generated}/paths.adoc[]

include::{generated}/security.adoc[]

include::{generated}/definitions.adoc[]

4.执行mvn package -Dmaven.test.skip=true，生成的接口文档在项目的target/asciidoc/pdf

！！！最后，asciidoctor-maven-plugin插件对中文的支持不够友好，可能会出现pdf中文的丢失或者乱码，需要对插件字体进行替换

1.在maven仓库中找到该jar包

2.找到jar之后，打开字体文件路径：asciidoctorj-pdf-1.5.0-alpha.10.1.jar\gems\asciidoctor-pdf-1.5.0.alpha.10\data\fonts

3.在fonts下面有以.ttf结尾的字体文件，使用哪个字体文件，就是在这里指定的，先把自己下载好的字体文件加进去

4.修改asciidoctorj-pdf-1.5.0-alpha.10.1.jar\gems\asciidoctor-pdf-1.5.0.alpha.10\data\themes下面的default-theme.yml配置文件：

5.修改完成之后，保存，再去执行生成命令mvn package -Dmaven.test.skip=true

网友评论

本文标题：swagger生成PDF接口文档

本文链接：https://www.haomeiwen.com/subject/ysrbkctx.html

延伸阅读

深度阅读

您也可以注册成为美文阅读网的作者，发表您的原创作品、分享您的心情！

swagger生成PDF接口文档

相关文章