Swagger2实现API文档的静态部署并支持导出PDF

• 如何使用
• 1、导包
• 2、加载配置类
• 3、在Controller里使用
• 4、运行项目

• 1、引入依赖
• 2、配置插件
• 3、编写测试程序，用来生成adoc文件
• 4、生成PDF文档并解决中文乱码问题

如何使用

1、导包

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

2、加载配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//加了ApiOperation注解的类，才生成接口文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//包下的类，才生成接口文档
.apis(RequestHandlerSelectors.basePackage("com.tpm.fis.modules"))
.paths(PathSelectors.any())
.build()
.securitySchemes(security());
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("API文档的标题 ")
.description("SpringBoot+MyBatis+Vue")
.termsOfServiceUrl("http://xxxx")
.version("3.0")
.build();
}
}

3、在Controller里使用

/**
* 系统配置信息
*
* @author
* @email
* @date 2016年12月4日 下午6:55:53
*/
@RestController
@RequestMapping("/sys/config")
@Api(tags = "i、参数管理", description = " ")
public class SysConfigController extends AbstractController {
@Autowired
private SysConfigService sysConfigService;

/**
* 所有配置列表
*/
@GetMapping("/list")
@RequiresPermissions("sys:config:list")
@ApiOperation(value = "参数列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "page", value = "页码",  dataType = "int", required = true,paramType = "query", defaultValue = "1"),
@ApiImplicitParam(name = "limit", value = "每页条数",  dataType = "int", required = true,paramType = "query", defaultValue = "10"),
@ApiImplicitParam(name = "sidx", value = "排序字段",  dataType = "String", required = false,paramType = "query" ),
@ApiImplicitParam(name = "order", value = "排序方式，如：asc、desc",  dataType = "String", required = false,paramType = "query"),
@ApiImplicitParam(name = "key", value = "参数名",  dataType = "String", required = false,paramType = "query")
})
public R list(@RequestParam Map<String, Object> params){
PageUtils page = sysConfigService.queryPage(params);

return R.ok().put("page", page);
}

/**
* 配置信息
*/
@GetMapping("/info/{id}")
@RequiresPermissions("sys:config:info")
@ApiOperation(value = "获取参数信息")
public R info(@PathVariable("id") Long id){
SysConfigEntity config = sysConfigService.selectById(id);

return R.ok().put("config", config);
}

/**
* 保存配置
*/
@SysLog("保存配置")
@PostMapping("/save")
@RequiresPermissions("sys:config:save")
@ApiOperation(value = "添加参数")
public R save(@RequestBody SysConfigEntity config){
ValidatorUtils.validateEntity(config);

sysConfigService.save(config);

return R.ok();
}

/**
* 修改配置
*/
@SysLog("修改配置")
@PostMapping("/update")
@RequiresPermissions("sys:config:update")
@ApiOperation(value = "修改参数")
public R update(@RequestBody SysConfigEntity config){
ValidatorUtils.validateEntity(config);

sysConfigService.update(config);

return R.ok();
}

/**
* 删除配置
*/
@SysLog("删除配置")
@PostMapping("/delete")
@RequiresPermissions("sys:config:delete")
@ApiOperation(value = "删除参数")
public R delete(@RequestBody Long[] ids){
sysConfigService.deleteBatch(ids);

return R.ok();
}

}

4、运行项目

浏览器输入http://localhost:8080/swagger-ui.html看看吧

静态部署

1、引入依赖

<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.10.1</version>
<scope>test</scope>
</dependency>

2、配置插件

<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.1</version>
<configuration>
<swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
<outputDir>src/docs/asciidoc/generated</outputDir>
<config>
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
</config>
</configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
<outputDirectory>src/docs/asciidoc/html</outputDirectory>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<toc>left</toc>
</attributes>
</configuration>
</plugin>

3、编写测试程序，用来生成adoc文件

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class DemoApplicationTests {

@Test
public void generateAsciiDocs() throws Exception {
//    输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withGeneratedExamples()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.build();

Swagger2MarkupConverter.from(new URL("http://localhost:8093/Kanban/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("src/docs/asciidoc/generated/api"));
}
@Test
public void generatePDF() {
//样式
String style = "pdf-style=E:\\themes\\theme.yml";
//字体
String fontsdir = "pdf-fontsdir=E:\\fonts";
//需要指定adoc文件位置
String adocPath = "D:\\workspace\\work\\intellijidea\\Kanban\\src\\docs\\asciidoc\\generated\\api.adoc";
AsciidoctorInvoker.main(new String[]{"-a",style,"-a",fontsdir,"-b","pdf",adocPath});
}
}

4、生成PDF文档并解决中文乱码问题

1、把https://github.com/asciidoctor/asciidoctor这个项目download下来,把目录下的data目录拷贝到E盘根目录下(当然哪都行啦)
2、去下载一个中文字体，后缀是.ttf结尾的，放到data/fonts目录里
3、复制data/themes/default-theme.yml为theme.yml，打开theme.yml并搜索mplus1p开头的文件名，换成5.2下载的中文字体
4、运行测试程序中的generatePDF生成pdf文件

参考

史上最简单的Swagger2实现API文档的静态部署并支持导出PDF并解决中文乱码问题