文档章节

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

程序猿DD
 程序猿DD
发布于 01/27 15:11
字数 1115
阅读 103
收藏 0
点赞 0
评论 0

在阅读本文之前,您先需要了解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(new URL("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版之前的文档也是这样的!!!

本文首发:http://blog.didispace.com/swagger2markup-asciidoc/

© 著作权归作者所有

共有 人打赏支持
程序猿DD
粉丝 336
博文 54
码字总数 72843
作品 0
闵行
Spring Cloud启动应用时指定IP或忽略某张网卡配置

说明:分布式应用部署到服务上,由于服务器可能存在多张网卡,造成IP地址不准的问题。 解决方法: 1、直接添加忽略某张网卡的配置: spring.cloud.inetutils.ignored-interfaces[0]=eth0 # ...

easonjim ⋅ 02/09 ⋅ 0

centos7源码安装git2.10.0版本

由于Centos7使用yum -y install git 安装的git版本是 git --version git version 1.9.x 想要升级到2.10.0: 升级安装git的时候,最好一次安装依赖。 yum install -y tk zlib-devel openssl-d...

南北二斗 ⋅ 04/13 ⋅ 0

Build RESTful APIs with Spring MVC: Swagger

Visualizes REST APIs with Swagger Swagger is widely used for visualizing APIs, and with Swagger UI it provides online sandbox for frontend developers. Visualizes REST APIs Sprin......

hantsy ⋅ 2016/07/25 ⋅ 0

使用springfox 集成swagger 与spring mvc

创建一个maven 模块 将springfox相关的配置都配置在一个单独的api模块中,可以把这个模块当成web应用跑起来。 在需要引入swagger注解的模块中引入相应的依赖。 在api模块中添加初始化swagger...

java9 ⋅ 2016/07/29 ⋅ 0

使用heartbeat来做HA集群

HA 即 (high available)高可用,又被叫做双机热备。 用于关键性业务。 简单理解就是,有两台机器A和B,正常是A提供服务,B待命闲置,当A宕机或服务宕掉,会切换至B机器继续提供服务。 两个...

余二五 ⋅ 2017/11/15 ⋅ 0

使用Asciidoc代替Markdown和Word撰写开发文档

开发文档一般都由Word或Markdown(格式)撰写,前则多见于企业项目,后则在开源界很流行。但在实际使用中总觉得不尽人意。 他们的不是 Word的问题 表现上:格式过于复杂,导致写出来的文档排...

孤岛旭日 ⋅ 2015/10/30 ⋅ 0

用Swagger调用Harbor Registry的REST API

本文原作者为开源企业级容器Registry Harbor项目的工程师王锟,主要介绍如何使用Harbor内置Swagger来测试和调用Harbor的API。笔者做了少量修改。 Swagger简介 Swagger是最流行的RESTful API...

project_harbor ⋅ 2016/04/21 ⋅ 0

Django部署静态文件

线上环境下部署静态文件 将静态文件部署到线上环境的基本步骤很简单:当静态文件改变时,运行collectstatic 命令收集静态文件,然后将该目录(STATICROOT) 搬到静态文件服务器上。根据STATICF...

楠木楠 ⋅ 2016/10/09 ⋅ 0

Springfox 2.6.0 发布,开源的 API doc 框架

Springfox 2.6.0 发布了,Springfox的前身是swagger-springmvc,是一个开源的API doc框架,可以将我们的Controller的方法以文档的形式展现。 改进内容: (#1498) Add pathsGroupedBy configu...

淡漠悠然 ⋅ 2016/10/09 ⋅ 10

文档格式化工具--AsciiDoc

AsciiDoc 是一个非常不错的文档格式化工具,使用它可以将一般的文本文档转换成 HTML 网页、Man 手册、以及 DocBook 等等。其输出的文档不仅可以包含常规的内容,而且对于数学公式或者音乐简谱...

匿名 ⋅ 2012/04/05 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

Mahout推荐算法之SlopOne

一、 算法原理 有别于基于用户的协同过滤和基于item的协同过滤,SlopeOne采用简单的线性模型估计用户对item的评分。如下图,估计UserB对ItemJ的偏好 图(1) 在真实情况下,该方法有如下几个...

xiaomin0322 ⋅ 21分钟前 ⋅ 0

LVM讲解

LVM是什么 LVM是 Logical Volume Manager(逻辑卷管理)的简写,它是Linux环境下对磁盘分区进行管理的一种机制,Linux用户安装Linux操作系统时遇到的一个常见的难以决定的问题就是如何正确地...

李超小牛子 ⋅ 30分钟前 ⋅ 0

mysql更改密码、连接mysql、mysql常用命令

1. 更改mysql的root账户密码: mysql中root账户和系统root不是一个账户 1.1 更改环境变量PATH,增加mysql绝对路径 由于mysql安装目录为/usr/local/mysql/,所以系统不能直接使用mysql,需把/...

laoba ⋅ 31分钟前 ⋅ 0

阿里云发布企业数字化及上云外包平台服务:阿里云众包平台

摘要: 阿里云正式发布旗下众包平台业务(网址:https://zhongbao.aliyun.com/),支持包括:网站定制开发,APP、电商系统等软件开发,商标、商品LOGO、VI、产品包装设计、营销推广、大数据人...

猫耳m ⋅ 31分钟前 ⋅ 0

阿里云发布企业数字化及上云外包平台服务:阿里云众包平台

摘要: 阿里云正式发布旗下众包平台业务(网址:https://zhongbao.aliyun.com/),支持包括:网站定制开发,APP、电商系统等软件开发,商标、商品LOGO、VI、产品包装设计、营销推广、大数据人...

阿里云云栖社区 ⋅ 35分钟前 ⋅ 0

1.03-Maven中使用ueditor富文本编辑器

起因:在maven仓库未找到百度的ueditor的jar包 操作: 1.下载百度的ueditor的jar包 2.打开命令行,切换到ueditor的下载位置,运行一下命令: mvn install:install-file -Dfile=ueditor-1.1....

静以修身2025 ⋅ 40分钟前 ⋅ 0

几道Spring 面试题

1、BeanFactory 接口和 ApplicationContext 接口有什么区别? ApplicationContext 接口继承BeanFactory接口 Spring核心工厂是BeanFactory BeanFactory采取延迟加载,第一次getBean时才会初始...

职业搬砖20年 ⋅ 50分钟前 ⋅ 0

包饺子

http://storage.slide.news.sina.com.cn/slidenews/77_ori/2018_24/74766_826131_625489.gif

霜叶情 ⋅ 51分钟前 ⋅ 0

xml解析

方法一: String s_xml1 = "<xml>" + "<head>lalalalal</head>" + "<body>1234</body>" + "</xml>"; try { DocumentBuilderFactory documentBuilderFactory......

GithubXD ⋅ 今天 ⋅ 0

reuse stream

Although Java streams were designed to be operated only once, programmers still ask how to reuse a stream. From a simple web search, we can find many posts with this same issue ......

idoz ⋅ 今天 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部