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

本文介绍如何使用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的配置了。

评论 2
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值