springboot集成swagger2生成html文件和pdf文件

最新推荐文章于 2025-07-15 14:58:36 发布

原创最新推荐文章于 2025-07-15 14:58:36 发布 · 7.1k 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#springboot #swagger

springboot 专栏收录该内容

7 篇文章

订阅专栏

本文介绍如何使用Swagger2配置Spring Boot项目，实现API文档自动生成，并导出为HTML及PDF格式。

虽然说是很简单的功能，但是在此记录一下

首先导入maven映射：

		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		    <version>2.6.1</version>
		</dependency>
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger-ui</artifactId>
		    <version>2.6.1</version>
		</dependency>

因为springfox包含了swagger2，所以我们直接引用springfox包下的swagger2就好了。第一个映射是swagger2的核心，第二个映射是swagger2显示的ui界面。

然后我们在项目里添加swagger2的配置类：

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurerAdapter {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx"))   //此处写入你的包名
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试接口文档")     //生成接口文档的title
                .description("测试接口文档说明")     //接口文档的描述
                .version("1.0")    //版本号
                .build();
    }
}

@EnableSwagger2这个注解代表了启动swagger2。

当我们配置好这个类之后启动项目直接可以访问项目节点：127.0.0.1:8080/swagger-ui.html

可以直接看到接口文档的一些摘要，是不是很简单。当然我们不止这些。

接下来我们配置生成html和pdf.

我们继续在pom文件添加：（注意是在properties节点下）

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
		<java.version>1.8</java.version>
		<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
                <asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
                <generated.asciidoc.directory>${project.build.directory}/asciidoc</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>
	</properties>

然后我们继续在plugins节点下添加打包插件：

     <plugins>
	<plugin>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-maven-plugin</artifactId>
	</plugin>
	<plugin>
		<groupId>org.apache.maven.plugins</groupId>
	       	<artifactId>maven-resources-plugin</artifactId>
	        <configuration>
		    <encoding>UTF-8</encoding>
		    <useDefaultDelimiters>true</useDefaultDelimiters>
	        </configuration>
	</plugin>
	<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!--生成PDF-->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.14</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>

                <!--文档生成配置-->
                <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>

                    <skip>false</skip>   <!-- 值为true 是在打包的时候跳过测试用例的执行，默认为false-->
                </configuration>
                <!--因为每次执行只能处理一个后端，所以对于每个想要的输出类型，都是独立分开执行-->
                <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>
	</plugins>

然后细心的已经看到生成html需要一个文件来支持，对就是index.doc文件。

我们需要在项目的根目录创建docs/asciidoc/index.adoc 这个index.adoc文件的内容是：

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

主要是把swagger2生成的文件内容渲染到我们需要的html或pdf。

接下来就是接口：

在接口也就是controller添加：

@RestController
@Api(value="测试控制器",tags={"测试操作接口"})
@RequestMapping(value = "/")
public class TestController {

	@ResponseBody
	@ApiOperation(value="测试", notes="测试方法")
	@RequestMapping(value = "/test",method = { RequestMethod.POST})
	public void test(@RequestBody TestBean testBean) {
	}
}

然后就是实体：

@ApiModel(value = "TestBean")
public class TestBean implements Serializable {
	private static final long serialVersionUID = 1L;

	@ApiModelProperty(value="传入id",required = true)
	private String id;
	
}

注解解释：

@Api 主要是在接口处，标示这个接口是做什么的

@ApiOperation主要在接口方法体，标示这个接口操作

@ApiModel 主要是在参数实体，标示这个实体是做什么的

@ApiModelProperty 参数实体的属性，标示属性作用（如果是必选项可以添加 required = true，默认是false）

添加测试用例:

@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest
public class ApplicationTests {

    private String snippetDir = "target/generated-snippets";
    private String outputDir  = "target/asciidoc";

    @Autowired
    private MockMvc mockMvc;

    @After
    public void Test() throws Exception {
        // 得到swagger.json,写入outputDir目录中
        mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
                .andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
                .andExpect(status().isOk())
                .andReturn();

        // 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir
        // 这个outputDir必须和插件里面<generated></generated>标签配置一致
        Swagger2MarkupConverter.from(outputDir + "/swagger.json")
                .withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
                .withExamples(snippetDir)
                .build()
                .intoFolder(outputDir);// 输出
        
    }
    @Test
    public void TestApi() throws Exception {}

}

因为插件是根据测试用例来生成html的，所以需要执行测试用例来完成最后一步。
至此，全部完成swagger2的配置了。