专栏首页专注于主流技术和业务使用Swagger2Markup实现导出API文档

使用Swagger2Markup实现导出API文档

前言

在学会了如何使用Swagger之后,我们已经能够轻松地为Spring MVC或SpringBoot的Web项目自动构建出API文档了。但是,构建的文档必须通过在项目中整合swagger-ui、或使用单独部署的swagger-ui/v2/api-docs返回的配置信息才能展现出您所构建的API文档。本文将在使用Swagger的基础上,再介绍一种生成静态API文档的方法,以便于构建更轻量部署和使用的API文档。 Swagger使用说明:REST API文档工具Swagger2,以及与SpringBoot的集成

Swagger2Markup简介

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

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

如何使用

在使用Swagger2Markup之前,我们先需要准备一个使用了Swagger的Web项目,REST API文档工具Swagger2,以及与SpringBoot的集成

生成AsciiDoc

生成AsciiDoc的方式有两种:

  1. 通过Java代码来生成

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

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
</dependency>
<repositories>
    <repository>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

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

/**
     * 生成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"));
    }

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

  • MarkupLanguage.ASCIIDOC:指定了要输出的最终格式。除了ASCIIDOC之外,还有MARKDOWN和CONFLUENCE_MARKUP
  • from(new URL("http://localhost:8080/v2/api-docs"):指定了生成静态部署文档的源头配置,可以是这样的URL形式,也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目,我们通过使用访问本地Swagger接口的方式,如果是从外部获取的Swagger文档配置文件,就可以通过字符串或读文件的方式
  • toFolder(Paths.get("src/docs/asciidoc/generated"):指定最终生成文件的具体目录位置 输出到单个文件

如果不想分割结果文件,也可以通过替换toFolder(Paths.get("src/docs/asciidoc/generated")toFile(Paths.get("src/docs/asciidoc/generated/all")),将转换结果输出到一个单一的文件中,这样可以最终生成html的也是单一的。 在执行了上面的测试用例之后,我们就能在当前项目的目录下获得如下内容:

image.png

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

  1. 通过Maven插件来生成

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

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>./docs/asciidoc/html</outputDirectory>
                    <headerFooter>true</headerFooter>
                    <doctype>book</doctype>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <!--菜单栏在左边-->
                        <toc>left</toc>
                        <!--多标题排列-->
                        <toclevels>3</toclevels>
                        <!--自动打数字序号-->
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>
            </plugin>

配置执行命令

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

image.png

腾讯云+社区邀请

我的博客即将搬运同步至腾讯云+社区,邀请大家一同入驻:https://cloud.tencent.com/developer/support-plan?invite_code=1eyx9f4wbftcp

本文参与 腾讯云自媒体分享计划 ,欢迎热爱写作的你一起参与!
本文分享自作者个人站点/博客:https://www.jianshu.com/u/e73a02fe13e2复制
如有侵权,请联系 cloudcommunity@tencent.com 删除。
登录 后参与评论
0 条评论

相关文章

  • 使用Swagger2Markup实现API文档的静态部署(一):AsciiDoc

    在阅读本文之前,您先需要了解Swagger的使用,如果您还不知道它是用来干嘛的,请先阅读《Spring Boot中使用Swagger2构建强大的RESTful ...

    程序猿DD
  • 使用Swagger2Markup实现API文档的静态部署(二):Markdown和Confluence

    在上一篇《使用Swagger2Markup实现API文档的静态部署(一):AsciiDoc》中,我们介绍了如何使用 Swagger2Markup将Swagger...

    程序猿DD
  • postman导出api文档

    阿超
  • 使用phpword插件实现word文档导出

    phpword的GitHub地址: https://github.com/PHPOffice/PHPWord

    猿哥
  • 使用 Oracle Datapump API 实现数据导出

      Oracle Datapump API 是基于PL/SQL实现的,是命令行方式下的补充。使用Datapump API可以将其逻辑备份特性将其集成到应用程序当...

    Leshami
  • apidoc实现API文档自动生成

    现在越来越流行前后端分离,使得前后端解耦。前后端的联系来源于数据接口,所以后端每次实现数据接口后都需要给前端写API接口文档,但是每次手写API...

    创译科技
  • 使用Gitbook创建文档并导出PDF

    导出PDF的方式有很多种,之前使用过马克飞象的导出功能,不过只是简单的导出并不能添加目录,因为源文件是markdown编写的,经过筛选后采用了gitbook的方...

    恒宇少年
  • 使用Google JS api 创建 文档

    https://developers.google.com/docs/api/reference/rest/v1/documents/request#Reque...

    拿我格子衫来
  • 使用bee自动生成api文档

    beego中的bee工具可以方便的自动生成api文档,基于数据库字段,自动生成golang版基于beego的crud代码,方法如下: 1、进入到gopath目录...

    用户1141560
  • 重学Spring系列之Swagger2.0和Swagger3.0

    当下很多公司都采取前后端分离的开发模式,前端和后端的工作由不同的工程师完成。在这种开发模式下,维护一份及时更新且完整的API 文档将会极大的提高我们的工作效率。...

    大忽悠爱学习
  • 使用japidocs生成springboot api文档

    将在C:\ProjectName\docs\V2.0\路径下生成文档文件 首页index.html效果如图

    路过君
  • 使用 YApi 管理 API 文档、测试、MOCK

    随着互联网的发展,API变的至关重要。根据统计,目前市面上有上千万的开发者,互联网项目超过10亿,保守统计涉及的 API 数量大约有 100 亿。这么大基数的A...

    肉眼品世界
  • Java中如何使用帮助文档(API)

      5:第一步:看包     java.lang包下的类不需要导入,其他的全部需要导入。     要导入:     java.util.Scanner

    黑泽君
  • [Swagger] Swagger 接口管理和文档导出

    title: date: 2018-08-25 19:22:00 categories:

    架构探险之道
  • 使用python删除word文档中的指定段落,顺便实现一下文档中的图片导出

    JQ实验室
  • Spring MVC中使用Swagger生成API文档

    实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率。 听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下。 一:Sw...

    Java架构师历程
  • [springboot 开发单体web shop] 4. Swagger生成Javadoc

    在日常的工作中,特别是现在前后端分离模式之下,接口的提供造成了我们前后端开发人员的沟通 成本大量提升,因为沟通不到位,不及时而造成的[撕币]事件都成了日常工作...

    Isaac Zhang
  • 使用PowerDesigner16.5 逆向数据库 导出word文档

    在上一篇《使用PowerDesigner16.5 逆向数据库生产表结构或导出word文档二》中,我们学会了使用PowerDesigner16.5怎么连接数据库,...

    凯哥Java

扫码关注腾讯云开发者

领取腾讯云代金券