swagger生成PDF

做开发的不免会有出文档的时候，有些硬性要求，要接口文档是PDF的形式 那么我们就利用swagger生成PDF接口文档

1.如果你的项目中已经有swagger配置以及相关依赖的话，只需要添加以下依赖以及测试方法即可。如若没有那么请按照2.中执行

依赖：

<!-- 导出pdf -->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

  <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.11</version>
                    </dependency>
                </dependencies>
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                    <backend>pdf</backend>
                </configuration>
            </plugin>

测试方法：

 

 private final String swaggerUrl = "F:\\y\\productJson3.txt";//本地存放json文件地址
    @Test
    public void generateMarkdownDocsToFile (){
        //    输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();


        Swagger2MarkupConverter.from(Paths.get(swaggerUrl))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/generated/markdown/all")); //all表示的是文件名
    }

2.项目中没有配置swagger：

swagger依赖
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

swagger配置类

package com.deepexi.product.common.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
@Profile({"dev"})
public class SwaggerConfig {
    //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        // 设置全局header中的Authorization参数非必填，传空也可以，方便swagger测试
        ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        ticketPar.name("Authorization")
                .description("Authorization验证")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build();
        pars.add(ticketPar.build());

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.deepexi.product.controller.web"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring cloud 脚手架使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("deepexi", "http://www.deepexi.com", "hudong@deepexi.com"))
                //版本号
                .version("1.0")
                //描述
                .description("api管理").build();
    }

}

然后再将1中的依赖，测试方法一并粘来。

json转换地址https://www.sojson.com/

PDF转换地址http://coolaf.com/tool/md

启动项目 访问swagger地址 localhost：项目的端口号/项目的服务名称/swagger-ui.html#/就可以出现swagger页面

点击红框则会生成json页面

复制json数据，注意千万不要复制<json> 标签，否则解析报错。将json数据复制保存为txt文件。在测试方法中更改json文件路径执行测试方法。成功后便可在项目中指定路径src/docs/generated/markdown/下生成all.md文件 这是个markdown文件将其文件内容复制到PDF转换地址http://coolaf.com/tool/md中便可预览接口文档

确保 生成的接口文档没有错误，点击下载PDF 即可。

注意⚠️！！

• 使用swagger生成接口文档必须在接口以及接口出入参数使用swagger注解 配套使用才能识别扫描接口生成文档 swagger注解的使用请参考我的这篇文章https://blog.youkuaiyun.com/cdliker/article/details/112213684。
• 按照以上方式生成的是项目中的全部接口。如要生成指定接口文档，则需从全部json数据中自行粘贴相关接口内容生成json文档==》md文档==》PDF文档
• 自行粘贴时需注意出入参数的粘贴：
  • 如果参数有使用swagger注解 请使用swagger注解中对该参数的描述名称进行搜索 否则搜索不到
  • 如果参数中有使用套用类例如：
    • 参数定义

      Payload<PageBean<PcProductItemPageVO>> 那么你则需要占四个参数类：PcProductItemPageVO，PageBean<PcProductItemPageVO>，Payload<PageBean<PcProductItemPageVO>> ，Payload

    • private List<PcProductUnitSaveForm> pcItemUnits 像这种参数类中的参数是对象或者是集合泛性是对象的这种也需要把PcProductUnitSaveForm的参数类粘出来。

    • 总之怎么粘需要查看全的json数据的结构，按照上边的结构进行粘贴。一定要仔细否则会出现参数类不显示参数只显示类地址的情况。