hooyantsing's Blog

青铜篇_P18_从swagger导出多种格式离线文档

字数统计: 619阅读时长: 3 min
2020/07/15

从swagger导出多种格式离线文档

20年全新-Spring Boot 2.x从青铜到王者之青铜篇-打造精品中的精品-程序员-编程-架构师-SpringBoot

导出格式路线图

198733cb3d305d19d14efdbff9fbe062.png

依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-core</artifactId>
<version>1.5.16</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.16</version>
</dependency>

实际上 springfox-swagger2 包含 swagger-models 。之所以要单独引入,是由于兼容性的问题。

经测试,以上三个依赖组合,是可以正常工作的。

swagger 格式导出 ASCIIDOC 或 Markdown 格式

代码方式

测试类里配置,就像是一个测试用例。

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
package xyz.hooy.demo.bronze.p18;

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit.jupiter.SpringExtension;

import java.net.URL;
import java.nio.file.Paths;

@ExtendWith(SpringExtension.class)
//使用默认端口,也就是application.properties里的server.port字段。
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class SwaggerExportTests {
@Test
public void generateAsciiDocs() throws Exception {
/**
* 导出文件的生成格式 ASCIIDOC 或 MARKDOWN
* 设置语言,中文
* 分组方式,和前面的 "将英文字段的名称翻译成中文" 一节的 "tags = "Article"" 相关联
*/
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();

/**
* .from 从哪里导出,从URL的路径导出
* .withConfig 导出器的配置
* .toFile 导出到哪里
*/
Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("src/main/resources/docs/asciidoc"));
}
}

ASCIIDOC 转换成 HTML 格式

Maven插件方式

pom.xml 文件内加入插件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<!--asciidoc 文件目录-->
<sourceDirectory>src/main/resources/docs</sourceDirectory>
<!--生成html的路径-->
<outputDirectory>src/main/resources/html</outputDirectory>
<backend>html</backend>
<attributes>
<!--导航栏在左-->
<toc>left</toc>
<!--显示层级数-->
<!-- <toclevels>3</toclevels>-->
<!--自动打数字序号-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>

最后

双击,执行。31a62a6fb94ae394c8492d65cc1917dc.png

CATALOG
  1. 1. 从swagger导出多种格式离线文档
    1. 1.1. 导出格式路线图
      1. 1.1.1. 依赖
    2. 1.2. swagger 格式导出 ASCIIDOC 或 Markdown 格式
      1. 1.2.1. 代码方式
    3. 1.3. ASCIIDOC 转换成 HTML 格式
      1. 1.3.1. Maven插件方式