微服务架构和分布式架构的区别，Spring Boot 2(1)

最新推荐文章于 2024-07-17 09:51:48 发布

2401_84008965

最新推荐文章于 2024-07-17 09:51:48 发布

阅读量806

点赞数 12

分类专栏：程序员文章标签：架构微服务分布式

本文链接：https://blog.csdn.net/2401_84008965/article/details/137945335

版权

程序员专栏收录该内容

274 篇文章 0 订阅

订阅专栏

在这两篇文章中，我们构建的文档必须通过在项目中整合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增加需要使用的相关依赖和仓库

…

io.github.swagger2markup

swagger2markup

1.3.3

test

false

jcenter-releases

jcenter

http://jcenter.bintray.com

本身这个工具主要就临时用一下，所以这里我们把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之外，还有MARKDOWN和CONFLUENCE_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的也是单一的。