SpringBoot + Swagger + IDEA 生成API接口文档导出PDF和HTML(加解决中文乱码)

本文链接：https://blog.youkuaiyun.com/Hannibal22/article/details/114978363

PS:查找他人教程，自己实践程序跑通后总结整理，主要用于防止以后再使用忘记。(相关代码复制官方demo 官方demoURL)

1.pom文件导入swagger依赖

1 <dependency>
 2              <groupId>io.springfox</groupId>
 3              <artifactId>springfox-swagger2</artifactId>
 4              <version>2.6.1</version>
 5         </dependency>
 6         <dependency>
 7             <groupId>io.springfox</groupId>
 8              <artifactId>springfox-swagger-ui</artifactId>
 9              <version>2.6.1</version>
10 </dependency>

2.添加配置文件

1 @Configuration
 2 @EnableSwagger2
 3 public class SwaggerConfig implements WebMvcConfigurer {
 4 
 5     @Override
 6     public void addResourceHandlers(ResourceHandlerRegistry registry) {
 7         registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
 8         registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
 9         registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
10     }
11 
12 
13     @Bean
14     public Docket createRestApi() {
15         return new Docket(DocumentationType.SWAGGER_2)
16                 .apiInfo(apiInfo())
17                 .select()
18                 //加了ApiOperation注解的类，才生成接口文档
19                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
20                 //包下的类，才生成接口文档
21                 .apis(RequestHandlerSelectors.basePackage("com.huawei.bmpserver.web.controller"))
22                 .paths(PathSelectors.any())
23                 .build()
24                 //在生产环境需要把swagger关闭，enable(false)
25                 .enable(true);
26     }
27 
28     private ApiInfo apiInfo() {
29         return new ApiInfoBuilder()
30                 .title("XXX公司")
31                 .description("XXXCRM-API文档")
32                 .termsOfServiceUrl("http://www.baidu.com/")
33                 .version("1.0")
34                 .build();
35     }
36 }

3.在contrallor和vo(对象等)中加入注解

1 @Controller
 2 @RequestMapping(value = "/users", produces = MediaType.APPLICATION_JSON_VALUE)
 3 @Api(value = "/users", tags = "Users", description = "Operations about user")
 4 public class UserController {
 5   UserRepository userRepository = new UserRepository();
 6 
 7   static class UserRepository extends MapBackedRepository<String, User> {
 8   }
 9 
10   @RequestMapping(method = POST)
11   @ResponseBody
12   @ApiOperation(value = "Create user", notes = "This can only be done by the logged in user.")
13   public ResponseEntity<User> createUser(
14           @RequestBody
15           @ApiParam(value = "Created user object", required = true) User user) {
16 
17     userRepository.add(user);
18     return new ResponseEntity<User>(user, HttpStatus.OK);
19   }
20 
21 }

contrallor注解

1 public class User {
2 @ApiModelProperty(value = "用户名称")
3   private String username;
4  @ApiModelProperty(value = "电子邮件")
5   private String email;
6   private String password;
7   private String phone;
8  }

对象注解

4.运行程序，进入网页 http://IP:port/v2/api-docs (例：http://localhost:8083/v2/api-docs ) 并右键下载json。

5.将下载的文件命名为 swagger.json 并放到 maven打包文件夹下。
在这里插入图片描述
6.下载swagger2markup项目 (地址：https://github.com/Swagger2Markup/spring-swagger2markup-demo )，将下载demo项目src文件夹下的docs文件夹复制到自己项目的src文件夹下。

7.pom文件加入swagger2markup的属性和相关配置

1 <properties>
 2         <swagger2markup.version>1.2.0</swagger2markup.version>
 3         <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory>
 4 
 5         <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
 6         <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>
 7         <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>
 8         <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
 9         <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
10 
11             <swagger.input>${swagger.output.dir}/swagger.json</swagger.input>
12 
13 </properties>

swagger2markup属性

1 <pluginRepositories>
 2         <pluginRepository>
 3             <id>jcenter-snapshots</id>
 4             <name>jcenter</name>
 5             <url>https://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
 6         </pluginRepository>
 7         <pluginRepository>
 8             <id>jcenter-releases</id>
 9             <name>jcenter</name>
10             <url>https://jcenter.bintray.com</url>
11             <snapshots>
12                 <enabled>false</enabled>
13             </snapshots>
14         </pluginRepository>
15     </pluginRepositories>
16 
17     <repositories>
18         <repository>
19             <id>jcentral</id>
20             <name>bintray</name>
21             <url>https://jcenter.bintray.com</url>
22             <snapshots>
23                 <enabled>false</enabled>
24             </snapshots>
25         </repository>
26         <repository>
27             <id>jcenter-snapshots</id>
28             <name>jcenter</name>
29             <url>https://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
30         </repository>
31     </repositories>

仓库配置

1 <!-- First, use the swagger2markup plugin to generate asciidoc -->
  2             <plugin>
  3                 <groupId>io.github.swagger2markup</groupId>
  4                 <artifactId>swagger2markup-maven-plugin</artifactId>
  5                 <version>${swagger2markup.version}</version>
  6                 <dependencies>
  7                     <dependency>
  8                         <groupId>io.github.swagger2markup</groupId>
  9                         <artifactId>swagger2markup-import-files-ext</artifactId>
 10                         <version>${swagger2markup.version}</version>
 11                     </dependency>
 12                     <dependency>
 13                         <groupId>io.github.swagger2markup</groupId>
 14                         <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
 15                         <version>${swagger2markup.version}</version>
 16                     </dependency>
 17                 </dependencies>
 18                 <configuration>
 19                     <swaggerInput>${swagger.input}</swaggerInput>
 20                     <outputDir>${generated.asciidoc.directory}</outputDir>
 21                     <config>
 22                         <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
 23                         <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
 24 
 25                         <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
 26                         <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
 27                         <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
 28                         <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath>
 29 
 30                         <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</swagger2markup.extensions.springRestDocs.snippetBaseUri>
 31                         <swagger2markup.extensions.springRestDocs.defaultSnippets>true</swagger2markup.extensions.springRestDocs.defaultSnippets>
 32                     </config>
 33                 </configuration>
 34                 <executions>
 35                     <execution>
 36                         <phase>test</phase>
 37                         <goals>
 38                             <goal>convertSwagger2markup</goal>
 39                         </goals>
 40                     </execution>
 41                 </executions>
 42             </plugin>
 43 
 44             <!-- Run the generated asciidoc through Asciidoctor to generate
 45                  other documentation types, such as PDFs or HTML5 -->
 46             <plugin>
 47                 <groupId>org.asciidoctor</groupId>
 48                 <artifactId>asciidoctor-maven-plugin</artifactId>
 49                 <version>1.5.6</version>
 50                 <!-- Include Asciidoctor PDF for pdf generation -->
 51                 <dependencies>
 52                     <dependency>
 53                         <groupId>org.asciidoctor</groupId>
 54                         <artifactId>asciidoctorj-pdf</artifactId>
 55                         <version>1.5.0-alpha.16</version>
 56                     </dependency>
 57                     <dependency>
 58                         <groupId>org.jruby</groupId>
 59                         <artifactId>jruby-complete</artifactId>
 60                         <version>1.7.21</version>
 61                     </dependency>
 62                 </dependencies>
 63                 <!-- Configure generic document generation settings -->
 64                 <configuration>
 65                     <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
 66                     <sourceDocumentName>index.adoc</sourceDocumentName>
 67                     <attributes>
 68                         <doctype>book</doctype>
 69                         <toc>left</toc>
 70                         <toclevels>3</toclevels>
 71                         <numbered></numbered>
 72                         <hardbreaks></hardbreaks>
 73                         <sectlinks></sectlinks>
 74                         <sectanchors></sectanchors>
 75                         <generated>${generated.asciidoc.directory}</generated>
 76                     </attributes>
 77                 </configuration>
 78                 <!-- Since each execution can only handle one backend, run
 79                      separate executions for each desired output type -->
 80                 <executions>
 81                     <execution>
 82                         <id>output-html</id>
 83                         <phase>test</phase>
 84                         <goals>
 85                             <goal>process-asciidoc</goal>
 86                         </goals>
 87                         <configuration>
 88                             <backend>html5</backend>
 89                             <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
 90                         </configuration>
 91                     </execution>
 92 
 93                     <execution>
 94                         <id>output-pdf</id>
 95                         <phase>test</phase>
 96                         <goals>
 97                             <goal>process-asciidoc</goal>
 98                         </goals>
 99                         <configuration>
100                             <backend>pdf</backend>
101                             <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
102                         </configuration>
103                     </execution>
104 
105                 </executions>
106             </plugin>

插件配置

8.所有配置完成后，控制台输入 mvn test 即可完成。

解决swagger导出pdf 中文乱码问题

1.下载后缀为 .ttf 的中文字体包如
在这里插入图片描述
2.进入maven仓库下的asciidoctorj-pdf包

以压缩包的方式打开。

3.将下载的字体放入到 asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\fonts 此文件夹中
在这里插入图片描述
4.修改asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\themes 文件夹下的 default-theme.yml文件。

具体修改内容为

Noto Serif 中四个参数修改为下载的字体包文件名。
保存完成。