springboot集成swagger2生成html文件和pdf文件
虽然说是很简单的功能，但是在此记录一下
首先导入maven映射：
io.springfox
springfox-swagger2
2.6.1
io.springfox
springfox-swagger-ui
2.6.1
因为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节点下）
UTF-8
UTF-8
1.8
${project.build.directory}/generated-snippets
${project.basedir}/docs/asciidoc
${project.build.directory}/asciidoc
${project.build.directory}/asciidoc/html
${project.build.directory}/asciidoc/pdf
然后我们继续在plugins节点下添加打包插件：
org.springframework.boot
spring-boot-maven-plugin
org.apache.maven.plugins
maven-resources-plugin
UTF-8
true
org.asciidoctor
asciidoctor-maven-plugin
1.5.3
org.asciidoctor
asciidoctorj-pdf
1.5.0-alpha.14
org.jruby
jruby-complete
1.7.21
${asciidoctor.input.directory}
index.adoc
book
left
3
${generated.asciidoc.directory}
<skip>falseskip>
output-html
test
process-asciidoc
html5
${asciidoctor.html.output.directory}
output-pdf
test
process-asciidoc
pdf
${asciidoctor.pdf.output.directory}
然后细心的已经看到生成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必须和插件里面至此，全部完成swagger2的配置了。