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

简介:

前言
在学会了如何使用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的方式有两种:

通过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的也是单一的。

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

本文由 程序猿DD-翟永超 创作




      本文转自yushiwh 51CTO博客,原文链接:http://blog.51cto.com/yushiwh/2064508,如需转载请自行联系原作者


相关文章
|
4天前
|
敏捷开发 测试技术 API
云效产品使用常见问题之代码仓库不支持API文档如何解决
云效作为一款全面覆盖研发全生命周期管理的云端效能平台,致力于帮助企业实现高效协同、敏捷研发和持续交付。本合集收集整理了用户在使用云效过程中遇到的常见问题,问题涉及项目创建与管理、需求规划与迭代、代码托管与版本控制、自动化测试、持续集成与发布等方面。
|
4天前
|
数据可视化 Linux API
如何在Linux使用docker部署Swagger Editor并实现无公网IP远程协同编辑API文档
如何在Linux使用docker部署Swagger Editor并实现无公网IP远程协同编辑API文档
|
1天前
|
存储 算法 关系型数据库
实时计算 Flink版产品使用合集之在Flink Stream API中,可以在任务启动时初始化一些静态的参数并将其存储在内存中吗
实时计算Flink版作为一种强大的流处理和批处理统一的计算框架,广泛应用于各种需要实时数据处理和分析的场景。实时计算Flink版通常结合SQL接口、DataStream API、以及与上下游数据源和存储系统的丰富连接器,提供了一套全面的解决方案,以应对各种实时计算需求。其低延迟、高吞吐、容错性强的特点,使其成为众多企业和组织实时数据处理首选的技术平台。以下是实时计算Flink版的一些典型使用合集。
15 4
|
4天前
|
测试技术 API 开发工具
📑教你如何编写一份 API 文档
API 文档是开发者理解和使用API的关键,它提供详细的说明、代码示例和调用过程,帮助创建无缝集成。好的API文档能提升开发人员体验,减少上手时间和维护成本,同时促进产品迭代。API有面向团队、合作伙伴和最终用户三种类型。编写文档时要考虑受众,提供清晰的概述、教程、认证信息、端点定义、状态码和错误码示例。维护更新与API同步的文档至关重要,遵循通俗语言、参考文档、示例和专人负责等最佳实践,确保全面性。GitHub、Twilio和Dropbox的API文档是良好示例。
|
4天前
|
缓存 运维 Serverless
Serverless 应用引擎产品使用之阿里函数计算中。将本地电脑上的项目文件部署到阿里云函数计算(FC)上并实现对外提供API和WebUI如何解决
阿里云Serverless 应用引擎(SAE)提供了完整的微服务应用生命周期管理能力,包括应用部署、服务治理、开发运维、资源管理等功能,并通过扩展功能支持多环境管理、API Gateway、事件驱动等高级应用场景,帮助企业快速构建、部署、运维和扩展微服务架构,实现Serverless化的应用部署与运维模式。以下是对SAE产品使用合集的概述,包括应用管理、服务治理、开发运维、资源管理等方面。
39 1
|
4天前
|
机器学习/深度学习 人工智能 API
人工智能平台PAI产品使用合集之机器学习PAI-EAS部署好后,服务的公网API和URL怎么配置
阿里云人工智能平台PAI是一个功能强大、易于使用的AI开发平台,旨在降低AI开发门槛,加速创新,助力企业和开发者高效构建、部署和管理人工智能应用。其中包含了一系列相互协同的产品与服务,共同构成一个完整的人工智能开发与应用生态系统。以下是对PAI产品使用合集的概述,涵盖数据处理、模型开发、训练加速、模型部署及管理等多个环节。
|
4天前
|
前端开发 Java 测试技术
IDEA 版 API 接口神器来了,一键生成文档,贼香!
IDEA 版 API 接口神器来了,一键生成文档,贼香!
75 0
|
4天前
|
API
工作流JBPM操作API删除流程&部署流程
工作流JBPM操作API删除流程&部署流程
16 0
|
4天前
|
API 数据库
工作流JBPM操作API部署流程
工作流JBPM操作API部署流程
22 0
|
4天前
|
分布式计算 DataWorks 大数据
DataWorks常见问题之使用API删除之前的部署文件失败如何解决
DataWorks是阿里云提供的一站式大数据开发与管理平台,支持数据集成、数据开发、数据治理等功能;在本汇总中,我们梳理了DataWorks产品在使用过程中经常遇到的问题及解答,以助用户在数据处理和分析工作中提高效率,降低难度。

热门文章

最新文章