zoukankan      html  css  js  c++  java
  • swagger 生成 api 文档 html

    https://cloud.tencent.com/developer/article/1332445

    使用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

    本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

    发表于 2018-09-10
  • 相关阅读:
    Python中所有的关键字
    关于selenium的8种元素定位
    对提示框的操作
    selenium+webservice进行百度登录
    MISCONF Redis is configured to save RDB snapshots, but is currently not able to persist on disk. Commands that may modify the data set are disabled...报错解决
    Vue中使用echarts
    npm WARN deprecated request@2.88.2: request has been deprecated, see https://github.com/request/request/issues/3142解决方法
    插入排序
    冒泡排序优化
    roject 'org.springframework.boot:spring-boot-starter-parent:XXX' not found 解决
  • 原文地址:https://www.cnblogs.com/javajetty/p/10922328.html
Copyright © 2011-2022 走看看