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

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

前言

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

Swagger2Markup简介

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

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

如何使用

在使用Swagger2Markup之前,我们先需要准备一个使用了Swagger的Web项目,可以是直接使用Swagger2的项目,也可以是使用了spring-boot-starter-swagger的项目,比如我仓库中的:https://github.com/dyc87112/swagger-starter-demo ,下面就来看看如何使用Swagger2Markup来创建AsciiDoc。

生成AsciiDoc

生成AsciiDoc的方式有两种:

  1. 通过Java代码来生成

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

<dependencies>
    ...

    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

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

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {

    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();

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

}

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

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

在执行了上面的测试用例之后,我们就能在当前项目的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的也是单一的。

  1. 通过Maven插件来生成

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

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <outputDir>src/docs/asciidoc/generated</outputDir>
        <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
        </config>
    </configuration>
</plugin>

生成HTML

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

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
           <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
           <outputDirectory>src/docs/asciidoc/html</outputDirectory>
           <backend>html</backend>
           <sourceHighlighter>coderay</sourceHighlighter>
           <attributes>
            <toc>left</toc>
          </attributes>
      </configuration>
</plugin>

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

是不是感觉似曾相识呢?是的,Spring Cloud的E版之前的文档也是这样的!!!

原文发布于微信公众号 - 程序猿DD(didispace)

原文发表时间:2018-01-24

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

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏冷冷

SpringMVC 文件下载时 浏览器不能正确显示另存的文件名

问题:通过打印输出流的方式把文件下载到本地,但是在firebox 中 下载的文件不显示文件的文件名,造成文件不能直接打开,其他浏览器可以直接打开. 原因: 主要...

2095
来自专栏Java学习123

linux mount -t用法

9165
来自专栏玩转JavaEE

Spring Cloud中Hystrix仪表盘与Turbine集群监控

Hystrix仪表盘,就像汽车的仪表盘实时显示汽车的各项数据一样,Hystrix仪表盘主要用来监控Hystrix的实时运行状态,通过它我们可以看到Hystrix...

4204
来自专栏技术小站

Spring,@Controller,@RequestMapping, @ResponseBody,@RequestParam

1063
来自专栏nnngu

JSP 和 Servlet 的工作原理和生命周期

JSP的英文名叫Java Server Pages,翻译为中文是Java服务器页面的意思,其底层就是一个简化的Servlet设计,是由sum公司主导参与建立的一...

3054
来自专栏运维技术迷

连仕彤博客pyenv环境部署

pyenv是一款Python多版本管理工具,它可以很好的管理Python解释器、Python版本和Python虚拟环境,对于日常开发中,是一款很有必要安装的利器...

3485
来自专栏杨熹的专栏

详解Mac配置虚拟环境Virtualenv,安装Python科学计算包

最近正在自学Python做科学计算,当然在很多书籍和公开课里最先做的就是安装Numpy, Scipy, Matplotlib等包,不过每次安装单独的包时,...

2938
来自专栏salesforce零基础学习

salesforce 零基础学习(二十九)Record Types简单介绍

在项目中我们可能会遇见这种情况,不同的Profile拥有不同的页面,页面中的PickList标签可能显示不同的值。这个时候,使用Record Types可以很便...

2046
来自专栏程序猿DD

Spring Boot开发Web应用

《SpringBoot快速入门》 中我们完成了一个简单的RESTful Service,体验了快速开发的特性。在留言中也有朋友提到如何把处理结果渲染到页面上。那...

2096
来自专栏腾讯Bugly的专栏

腾讯Bugly Unity3D Plugin使用指南

概述 Bugly Unity Plugin是专为基于Unity引擎开发的跨移动平台(iOS/Android)游戏APP而开发的异常监控插件,它能够自动捕...

5295

扫码关注云+社区

领取腾讯云代金券