Swagger使用以及导出接口文档 PDF/html

最新推荐文章于 2025-04-08 10:35:36 发布

赖胖子的csdn

最新推荐文章于 2025-04-08 10:35:36 发布

阅读量1.2k

点赞数

分类专栏： # Spring

本文链接：https://blog.youkuaiyun.com/I_am_Yong_Ge/article/details/102497788

版权

Spring 专栏收录该内容

33 篇文章

订阅专栏

本文详细介绍了使用Swagger生成API文档的方法，包括将文档导出为html或PDF格式，解决了生成过程中遇到的问题，并提供了中文版文档汇总到单个文件的解决方案。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

文章目录

如果自动生成的PDF不合适，建议使用Typora软件，把md文件导出成PDF，需要word的时候，通过福昕高级PDF编辑器把PDF转word即可，效果还不错

一、详细了解Swagger使用

https://blog.youkuaiyun.com/sanyaoxu_2/article/details/80555328

二、导出Swagger的文档为html或者PDF

1.https://blog.youkuaiyun.com/qq_29534483/article/details/81227308
2.https://blog.youkuaiyun.com/qq_29534483/article/details/81235081

或者参考：
https://www.cnblogs.com/wg1234/p/9962237.html

三、遇到的问题以及解决方案

学习2.1的时候，发现生成不了PDF文件，采用下面2条命令，就能解决
mvn swagger2markup:convertSwagger2markup
mvn generate-resources

但是，生成了多个PDF，还是英文的，觉得不好看，结果发现个大神，不但生成的文档是中文版的，还能汇总到一个文件中
使用Swagger2Markup实现导出API文档

学习2.2的时候，生成了一个jar包，以后可以直接使用
下载地址
https://download.youkuaiyun.com/download/i_am_yong_ge/11852322
完整代码
https://github.com/Leo-ljy/SwaggerToPdf

代码记录下
先执行下面一个测试用例，然后调用下面指令，就完工了

mvn generate-resources

/**
     * 生成AsciiDocs格式文档
     * @throws Exception
     */
    @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://127.0.0.1:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/asciidoc/generated"));
    }

    /**
     * 生成Markdown格式文档
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocs() throws Exception {
        //    输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/markdown/generated"));
    }
    /**
     * 生成Confluence格式文档
     * @throws Exception
     */
    @Test
    public void generateConfluenceDocs() throws Exception {
        //    输出Confluence使用的格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/confluence/generated"));
    }

    /**
     * 生成AsciiDocs格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() 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:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
    }

    /**
     * 生成Markdown格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocsToFile() throws Exception {
        //    输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/markdown/generated/all"));
    }