导航：首页 > 互联网科技 >

Swagger静态文档的生成方法

发表于：2024-11-16 作者：千家信息网编辑

千家信息网最后更新 2024年11月16日，本篇内容主要讲解"Swagger静态文档的生成方法"，感兴趣的朋友不妨来看看。本文介绍的方法操作简单快捷，实用性强。下面就让小编来带大家学习"Swagger静态文档的生成方法"吧!Swagger2Ma

千家信息网最后更新 2024年11月16日Swagger静态文档的生成方法

本篇内容主要讲解"Swagger静态文档的生成方法"，感兴趣的朋友不妨来看看。本文介绍的方法操作简单快捷，实用性强。下面就让小编来带大家学习"Swagger静态文档的生成方法"吧!

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。

项目主页：https://github.com/Swagger2Markup/swagger2markup

如何使用

在使用Swagger2Markup之前，我们先需要准备一个使用了Swagger的Web项目，可以是直接使用Swagger2的项目，也可以使用Spring Boot 2.x基础教程：使用Swagger2构建强大的API文档一文中构建的项目。读者可以通过下面的仓库获取：

Github：https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
Gitee：https://gitee.com/didispace/SpringBoot-Learning/tree/2.x

接下来，我们将利用这个项目中的chapter2-2模块作为基础来来生成几种不同格式的静态文档。

生成 AsciiDoc 文档

生成 AsciiDoc 文档的方式有两种：

通过Java代码来生成

第一步：编辑pom.xml增加需要使用的相关依赖和仓库

    ...            io.github.swagger2markup        swagger2markup        1.3.3        test                            false                jcenter-releases        jcenter        http://jcenter.bintray.com

本身这个工具主要就临时用一下，所以这里我们把scope设置为test，这样这个依赖就不会打包到正常运行环境中去。

第二步：编写一个单元测试用例来生成执行生成文档的代码

@RunWith(SpringRunner.class)@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)public class DemoApplicationTests {    @Test    public void generateAsciiDocs() throws Exception {        URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");        Path outputDirectory = Paths.get("src/docs/asciidoc/generated");        //    输出Ascii格式        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)                .build();        Swagger2MarkupConverter.from(remoteSwaggerFile)                .withConfig(config)                .build()                .toFolder(outputDirectory);    }}

以上代码内容很简单，大致说明几个关键内容：

MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP，分别定义了其他格式，后面会具体举例。
from(remoteSwaggerFile：指定了生成静态部署文档的源头配置，可以是这样的URL形式，也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目，我们通过使用访问本地Swagger接口的方式，如果是从外部获取的Swagger文档配置文件，就可以通过字符串或读文件的方式
toFolder(outputDirectory)：指定最终生成文件的具体目录位置

在执行了上面的测试用例之后，我们就能在当前项目的src目录下获得如下内容：

src--docs----asciidoc------generated--------definitions.adoc--------overview.adoc--------paths.adoc--------security.adoc

可以看到，这种方式在运行之后就生成出了4个不同的静态文件。

输出到单个文件

如果不想分割结果文件，也可以通过替换toFolder(Paths.get("src/docs/asciidoc/generated")为toFile(Paths.get("src/docs/asciidoc/generated/all"))，将转换结果输出到一个单一的文件中，这样可以最终生成html的也是单一的。

通过 Maven 插件来生成

除了通过上面编写Java代码来生成的方式之外，swagger2markup还提供了对应的Maven插件来使用。对于上面的生成方式，完全可以通过在pom.xml中增加如下插件来完成静态内容的生成。

    io.github.swagger2markup    swagger2markup-maven-plugin    1.3.3            http://localhost:8080/v2/api-docs        src/docs/asciidoc/generated-by-plugin                    ASCIIDOC

在使用插件生成前，需要先启动应用。然后执行插件，就可以在src/docs/asciidoc/generated-by-plugin目录下看到也生成了上面一样的adoc文件了。

生成HTML

在完成了从Swagger文档配置文件到AsciiDoc的源文件转换之后，就是如何将AsciiDoc转换成可部署的HTML内容了。这里继续在上面的工程基础上，引入一个Maven插件来完成。

    org.asciidoctor    asciidoctor-maven-plugin    1.5.6                 src/docs/asciidoc/generated             src/docs/asciidoc/html             html             coderay                         left

通过上面的配置，执行该插件的asciidoctor:process-asciidoc命令之后，就能在src/docs/asciidoc/html目录下生成最终可用的静态部署HTML了。在完成生成之后，可以直接通过浏览器来看查看，你就能看到类似下图的静态部署结果：

是不是感觉似曾相识呢？是的，Spring Cloud的E版之前的文档也是这样的！！！

Markdown 与 Confluence 的支持

要生成Markdown和Confluence的方式非常简单，与上一篇中的方法类似，只需要修改一个参数即可。

生成 Markdown 和 Confluence 文档

生成方式有一下两种：

通过Java代码来生成：只需要修改withMarkupLanguage属性来指定不同的格式以及toFolder属性为结果指定不同的输出目录。

生成markdown的代码片段：

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");Path outputDirectory = Paths.get("src/docs/markdown/generated");//    输出Ascii格式Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()    .withMarkupLanguage(MarkupLanguage.MARKDOWN)    .build();Swagger2MarkupConverter.from(remoteSwaggerFile)    .withConfig(config)    .build()    .toFolder(outputDirectory);

生成confluence的代码片段：

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");Path outputDirectory = Paths.get("src/docs/confluence/generated");//    输出Ascii格式Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)    .build();Swagger2MarkupConverter.from(remoteSwaggerFile)    .withConfig(config)    .build()    .toFolder(outputDirectory);

在执行了上面的设置内容之后，我们就能在当前项目的src目录下获得如下内容：

src--docs----confluence------generated--------definitions.txt--------overview.txt--------paths.txt--------security.txt----markdown------generated--------definitions.md--------overview.md--------paths.md--------security.md

可以看到，运行之后分别在markdown和confluence目录下输出了不同格式的转换内容。如果读者想要通过插件来生成，直接参考上一节内容，只需要修改插件配置中的swagger2markup.markupLanguage即可支持输出其他格式内容。

最后，我们一起来看看生成的Markdown和Confluence文档要怎么使用