Swagger2生成在线接口文档并导出pdf文件

一，配置

1，pom依赖

在pom.xml中添加相关依赖

 	<properties>
        <swagger.version>2.9.2</swagger.version>
    </properties>
    <dependencies>
  		<!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- swagger ui springfox -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
    </dependencies>

2，通用配置

@EnableSwagger2
@Configuration
public class Swagger2Config implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        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/");
    }

    //配置content type
    private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES =
            new HashSet<String>(Arrays.asList("application/json"));//,"application/xml"，只需要json格式

    @Bean
    public UiConfiguration uiConfiguration(){
        return UiConfigurationBuilder.builder()
                // 隐藏UI上的Models模块：-1为不显示，默认为0显示
                .defaultModelsExpandDepth(0)
                .build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("xmliu")// 不能为中文，否则termsOfServiceUrl打不开
                .consumes(DEFAULT_PRODUCES_AND_CONSUMES)
                .produces(DEFAULT_PRODUCES_AND_CONSUMES)
                .useDefaultResponseMessages(false)//不使用默认相应code
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.xmliu.swagger.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger测试项目")
                .contact(new Contact("liuxunming","liuxunming.com","diyangxia@163.com"))
                .description("swagger测试API接口文档")
                .termsOfServiceUrl("http://www.liuxunming.com/")
                .version("1.0")
                .build();
    }
}

二，注解

• Api
• ApiOperation
• ApiResponses ApiResponse
• ApiImplicitParams ApiImplicitParam
• ApiIgnore
• ApiModel ApiModelProperty

@Api(tags = "健康API接口")
@Controller
@RequestMapping("/health")
public class HealthController {

    @Autowired
    private HealthService healthService;

    @ApiOperation(value="查询", notes="条件查询",hidden = false)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "返回所有数据",response = Health.class)
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name="name",value="名字",required=false,paramType="form"),
            @ApiImplicitParam(name="address",value="住址",required=false,paramType="form"),
            @ApiImplicitParam(name="level",value="等级",required=false,paramType="form",dataType="Integer")
    })
    @GetMapping(value = "allData")
    @ResponseBody
    public ServerResponse allData(@RequestParam (required = false) String id){
        List<Health> list = healthService.findList();
        return ServerResponse.success().put("list",list);
    }
 }

三，主题

1，默认主题效果

2，添加依赖

 <!-- swagger ui bootstrap -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.1</version>
        </dependency>

3，添加配置

        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

4，启动看效果

四，token验证

方法1，所有接口上添加

@Bean
    public Docket createRestApi() {
		ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        ticketPar.name("Authorization").description("token每次请求都需带上，否则无法通过过滤器（登录登出无需），值为登录返回的token值")
                .modelRef(new ModelRef("string")).parameterType("header")
                //header中的ticket参数非必填，传空也可以
                .required(false).build();
        //根据每个方法名也知道当前方法在设置什么参数
        pars.add(ticketPar.build());
        
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("xmliu")// 不能为中文，否则termsOfServiceUrl打不开
                .consumes(DEFAULT_PRODUCES_AND_CONSUMES)
                .produces(DEFAULT_PRODUCES_AND_CONSUMES)
                .useDefaultResponseMessages(false)//不使用默认相应code
                .globalOperationParameters(pars)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.xmliu.swagger.web"))
                .paths(PathSelectors.any())
                .build();
    }

每个接口都会要输入一遍token，比较麻烦，推荐使用方法2

方法2，全局统一添加

 @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("atab")
                .consumes(DEFAULT_PRODUCES_AND_CONSUMES)
                .produces(DEFAULT_PRODUCES_AND_CONSUMES)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.xmliu.swagger.web"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())    // token验证
                .securityContexts(securityContexts()); // token验证
    }

  /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<SecurityScheme> securitySchemes()
    {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
        return apiKeyList;
    }

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts()
    {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
//                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
                        .build());
        return securityContexts;
    }

    /**
            * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth()
    {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

在swagger右上角有一个 Authorize 按钮，点击后弹出下面弹框，只需要输入一遍token

五，文件

设置maven国内镜像，配置maven环境变量，添加exclusions去掉多余的依赖，生成pdf成功，解决中文乱码问题，原因在于原有jar包中的字体文件对中文支持不友好，加入新的字体文件即可。
生成pdf文件，解决中文丢失
adoc-html-pdf

1，配置依赖

  		<dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
            <exclusions>
                <exclusion>
                    <groupId>nl.jworks.markdown_to_asciidoc</groupId>
                    <artifactId>markdown_to_asciidoc</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>ch.netzwerg</groupId>
                    <artifactId>paleo-core</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

2，添加插件，放在pom中build-plugins标签内

  <!--此插件生成ASCIIDOC-->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.2.0</version>
                <configuration>
                    <!--此处端口一定要是当前项目启动所用的端口-->
                    <swaggerInput>http://localhost:8084/</swaggerInput>
                    <outputDir>src/docs/asciidoc/generated</outputDir>
                    <config>
                        <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>
            <!--此插件生成HTML和PDF-->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.16</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.24</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                        </configuration>
                    </execution>
                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
            </plugin>

3，新建测试类，并运行生成相关文件

@RunWith(SpringRunner.class)
@SpringBootTest
public class PdfTest {

    @Test
    public void generateAsciiDocs() throws Exception {

        // 输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH).withPathsGroupedBy(GroupBy.TAGS).withGeneratedExamples()
                .withoutInlineSchema().build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs?group=xmliu")).withConfig(config)
                .build().toFolder(Paths.get("src/docs/asciidoc/generated"));
    }

}

4，中文乱码或丢失问题

核心思路就是替换字体，原因就是asciidoctorj-pdf对中文支持不友好

（1）首先找到这个jar

（2）用压缩软件打开这个jar，到如下目录，

（3）先加入不同类型的字体文件，比如粗体、斜体等，一共四种

字体文件如果没有合适的可从这里下载，https://download.csdn.net/download/diyangxia/19266310

（4）再修改themes中的配置文件default-themes.yml中字体指向即可

font:
  catalog:
    # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
    Noto Serif:
      normal: KaiGenGothicCN-Regular.ttf
      bold: KaiGenGothicCN-Bold.ttf
      italic: KaiGenGothicCN-Regular-Italic.ttf
      bold_italic: KaiGenGothicCN-Bold-Italic.ttf

5，执行命令

mvn asciidoctor:process-asciidoc

mvn generate-resources

六，参考文档

Swagger2导出Html和pdf文件

swagger2导出html文档和pdf文档（解决pdf中文乱码与显示不全问题）

springboot项目集成 swagger2, 并生成离线html和pdf文档（已解决pdf中文乱码问题）

SWAGGER+ASCIIDOCTOR 导出PDF中文缺失乱码问题解决

七，Github

https://github.com/xmliu/swaggerDemo

knife4j 增强型swagger

https://gitee.com/xiaoym/knife4j

在线预览