SpringBoot(十) Swagger2 - 进阶

使用Swagger2Markup实现API文档的静态部署

Swagger2Markup简介

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

Swagger2Markup示例

添加依赖

1
2
3
4
5
6
<!-- 添加Swagger2markup依赖 -->
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.3</version>
</dependency>

测试类

先启动SpringBoot项目, 再运行测试类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
@RunWith(SpringRunner.class)
@SpringBootTest
public class Springboot210ApplicationTests {


/**
* 输出Ascii格式
*/
@Test
public void generateAsciiDocs() throws MalformedURLException {
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"));
}

/**
* 输出Markdown格式
*/
@Test
public void generateMarkdownDocs() throws Exception {
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.build();

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

/**
* 输出Confluence使用的格式
*/
@Test
public void generateConfluenceDocs() throws Exception {
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
.build();

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

/**
* 输出Ascii到单文件
*/
@Test
public void generateAsciiDocsToFile() throws Exception {
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.build();

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

/**
* 输出Markdown到单文件
*/
@Test
public void generateMarkdownDocsToFile() throws Exception {
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.build();

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

}

简单说明

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

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

生成结果

在执行了上面的测试方法后,我们就能在当前项目的src目录下获得如下内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
src
--docs
----asciidoc
------generated
--------all.adoc
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc
----confluence
------generated
--------definitions.txt
--------overview.txt
--------paths.txt
--------security.txt
----markdown
------generated
--------all.md
--------definitions.md
--------overview.md
--------paths.md
--------security.md

生成HTML

除了通过上面编写Java代码来生成的方式之外,swagger2markup还提供了对应的Maven插件来使用。
生成HTML操作方法: 运行测试类基础后, 再运行Maven插件即可

修改pom.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<plugins>
<!-- 生成Asciidoc -->
<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 -->
<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>

<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>

配置Maven插件

通过上面的配置,执行该插件的 asciidoctor:process-asciidoc 命令

在src/docs/asciidoc/html目录下生成最终可用的静态部署HTML了。

1
2
3
4
5
6
7
8
9
src
--docs
----asciidoc
------html
--------all.html
--------definitions.html
--------overview.html
--------paths.html
--------security.html

查看all.html

-------------- 本文结束  感谢您的阅读 --------------