文档章节

Spring Boot 2.x基础教程:Swagger静态文档的生成

程序猿DD
 程序猿DD
发布于 10/16 10:32
字数 2142
阅读 32
收藏 0

前言

通过之前的两篇关于Swagger入门以及具体使用细节的介绍之后,我们已经能够轻松地为Spring MVC的Web项目自动构建出API文档了。如果您还不熟悉这块,可以先阅读:

在这两篇文章中,我们构建的文档必须通过在项目中整合swagger-ui、或使用单独部署的swagger-ui/v2/api-docs返回的配置信息才能展现出您所构建的API文档。而有些时候,我们可能只需要提供静态文档给其他对接方的时候,我们要如何快速轻便的产生静态API文档呢?

接下来我们就来学习一个解决该问题的工具:Swagger2Markup

Swagger2Markup简介

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

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

如何使用

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

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

生成 AsciiDoc 文档

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

通过Java代码来生成

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

<dependencies>
    ...

    <dependency>
        <groupid>io.github.swagger2markup</groupid>
        <artifactid>swagger2markup</artifactid>
        <version>1.3.3</version>
        <scope>test</scope>
    </dependency>
</dependencies>

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

本身这个工具主要就临时用一下,所以这里我们把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之外,还有MARKDOWNCONFLUENCE_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中增加如下插件来完成静态内容的生成。

<plugin>
    <groupid>io.github.swagger2markup</groupid>
    <artifactid>swagger2markup-maven-plugin</artifactid>
    <version>1.3.3</version>
    <configuration>
        <swaggerinput>http://localhost:8080/v2/api-docs</swaggerinput>
        <outputdir>src/docs/asciidoc/generated-by-plugin</outputdir>
        <config>
            <swagger2markup.markuplanguage>ASCIIDOC</swagger2markup.markuplanguage>
        </config>
    </configuration>
</plugin>

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

生成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版之前的文档也是这样的!!!

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文档要怎么使用

Markdown的部署

Markdown目前在文档编写中使用非常常见,所以可用的静态部署工具也非常多,比如:Hexo、Jekyll等都可以轻松地实现静态化部署,也可以使用一些SaaS版本的文档工具,比如:语雀等。具体使用方法,这里按照这些工具的文档都非常详细,这里就不具体介绍了。

Confluence的部署

相信很多团队都使用Confluence作为文档管理系统,所以下面具体说说Confluence格式生成结果的使用。

第一步:在Confluence的新建页面的工具栏中选择{}Markup

img

第二步:在弹出框的Insert选项中选择Confluence Wiki,然后将生成的txt文件中的内容,黏贴在左侧的输入框中;此时,在右侧的阅览框可以看到如下图的效果了。

img

注意:所以Insert选项中也提供了Markdown格式,我们也可以用上面生成的Markdown结果来使用,但是效果并不好,所以在Confluence中使用专门的生成结果为佳。

代码示例

本文的完整工程可以查看下面仓库中的chapter2-5目录:

如果您觉得本文不错,欢迎Star支持,您的关注是我坚持的动力!

参考资料

> 欢迎关注我的公众号:程序猿DD,获得独家整理的学习资源和日常干货推送。 > 如果您对我的专题内容感兴趣,也可以关注我的博客:didispace.com

© 著作权归作者所有

程序猿DD

程序猿DD

粉丝 697
博文 119
码字总数 167155
作品 4
闵行
私信 提问
Swagger2与Spring REST Docs

编者注 之前让其他写服务端的小伙伴支持swagger,然后最近一直在写Unity,没有把之前的项目和Swagger进行集成 Swagger Core Swagger Core Git Swagger 2.X 快速开始 注意:Swagger 2.x 遵循O...

抢小孩糖吃
02/21
208
0
精通Spring Boot——第九篇:整合Swagger在线文档

开发中最烦的一件事是什么?当你全心全意思考的时候,前端笑眯眯的过来了:“大哥,你没告诉我该传什么参数!”......然后一堆吧啦吧啦扯淡,好了,前端大佬心满意足的走了,你以为事情也就这...

liu浪诗人
2018/10/14
248
5
Spring Boot 集成 Swagger,生成接口文档就这么简单!

之前的文章介绍了《推荐一款接口 API 设计神器!》,今天栈长给大家介绍下如何与优秀的 Spring Boot 框架进行集成,简直不能太简单。 你所需具备的基础 告诉你,Spring Boot 真是个牛逼货! ...

Java技术栈
03/19
122
0
程序猿DD/swagger-butler

Swagger Butler Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用,增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起,...

程序猿DD
2018/05/25
0
0
smart-doc 1.7.0 重磅发布,Java 零注解文档生成工具

smart-doc是一个java restful api文档生成工具,smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。 smart-doc完全基于接口源码分析来生成接口文档,完全做到零注解...

上官胡闹
10/08
2.7K
11

没有更多内容

加载失败,请刷新页面

加载更多

OSChina 周五乱弹 —— 你已经是个成熟的熊猫了

Osc乱弹歌单(2019)请戳(这里) 【今日歌曲】 @Sharon啊 :#今日歌曲推荐# 分享黑鸭子的单曲《羞答答的玫瑰静悄悄的开》 《羞答答的玫瑰静悄悄的开》- 黑鸭子 手机党少年们想听歌,请使劲儿...

小小编辑
23分钟前
83
8
结合Spring Security进行web应用会话安全管理

在本文中,将为大家说明如何结合Spring Security 和Spring Session管理web应用的会话。 一、Spring Security创建使用session的方法 Spring Security提供4种方式精确的控制会话的创建: alwa...

fightinging
28分钟前
3
0
83、Mybatis和Hibernate重要区别

Mybatis;入门简单,程序容易上手开发,节省开发成本。Mybatis需要程序猿自己编写sql语句,是一个不完全的ORM框架,对sql修改和优化非常容易实现。 Mybatis适合开发需求变更频繁的系统,比如...

lianbang_W
今天
5
0
设计模式之状态模式

定义 Allow an object to alter its behavior when its internal state changes.The object will appear to change its class.(当一个对象内在状态改变时允许其改变行为,这个对象看起来像改...

陈年之后是青葱
今天
6
0
Python常用模块之os.path

os.path.abspath(path) 输入相对路径,返回绝对路径 Python 3.7.0 (v3.7.0:1bf9cc5093, Jun 27 2018, 04:59:51) [MSC v.1914 64 bit (AMD64)] on win32Type "copyright", "credits" or "lic......

松鼠大帝
今天
11
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部