Gradle环境下的Swagger接口文档PDF导出教程

在Gradle环境中，将Swagger（一个流行的API文档生成工具）转换为PDF格式是一项实用的操作，特别是在团队协作或交付完整文档时。本文将详细介绍如何在Spring Boot 2.1.6.RELEASE项目中利用Swagger 2.9.2、Swagger2Markup 1.3.3和asciidoctor等工具，配合Gradle 4.10.3，实现Swagger文档的自动化导出。 首先，确保您的项目已集成Swagger支持，通过@Configuration注解启用Swagger2，如`@EnableSwagger2`。配置一个`Docket` bean，定义API的版本信息、标题等，例如： ```java @Configuration @EnableSwagger2 class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.jptangchina.gradle.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Swagger2MarkupTestApi") .version("1.0") .build(); } } ``` 接下来，在`@RestController`中添加`@ApiOperation`注解，以便在Swagger中展示清晰的接口描述。例如，一个用户登录接口的定义： ```java @RestController @RequestMapping("/user") @Api(tags="用户接口") public class UserController { @ApiOperation("用户登录") @PostMapping @ResponseBody public Object userLogin(@RequestBody User user) { // ...处理登录逻辑 } } ``` 为了将Swagger文档转换为PDF，你需要引入Swagger2Markup和asciidoctor库，通过Gradle的dependencies添加它们： ```groovy dependencies { implementation 'io.springfox:springfox-swagger2:2.9.2' implementation 'io.springfox:springfox-swagger-ui:2.9.2' implementation 'io.github.swagger2markup:swagger2markup:1.3.3' implementation 'org.asciidoctor:asciidoctorj-pdf:1.5.8' testImplementation 'org.springframework.restdocs.mockmvc:spring-restdocs-mockmvc:2.1.6.RELEASE' } ``` 然后，创建一个工具类或者使用Gradle插件来执行Swagger到PDF的转换。这通常涉及以下几个步骤： 1. 获取Swagger API JSON：在Spring Boot应用启动后，可以通过`RestDocumentation`或`spring-restdocs-mockmvc`收集API文档。 2. 使用Swagger2Markup将JSON转换为 AsciiDoc格式：该库允许你将Swagger规范转换为易于阅读和格式化的文本。 3. 使用Asciidoctor渲染 AsciiDoc为PDF：Asciidoctor是一个强大的文档处理工具，可以将纯文本转换为各种输出格式，包括PDF。 示例插件代码可能如下： ```groovy task generateSwaggerPdf(type: Exec) { group = 'build' description = 'Generate Swagger documentation as PDF' executable = 'asciidoctor' args 'your_swagger.asciidoc', '-a', 'safe=server', '-o', 'swagger.pdf' } ``` 在`your_swagger.asciidoc`文件中，你可以引用生成的AsciiDoc内容，格式化好标题、章节和表格等元素。 通过上述步骤，你可以在Gradle环境下自动化地将Swagger接口文档转换为PDF格式，便于分享和存储。这个过程不仅提高了效率，也保持了文档的一致性和准确性。