Swagger静态文档的生成

利用Swagger自动生成漂亮的静态开发文档说明页 效果 利用Swagger自动生成漂亮的静态文档说明页 地址:https://t.itmuch.com/doc.html 总体步骤 •整合Swagger,生成Swagger描述端点 /v2/api-docs •使用 swagger2markup-maven-plugin ,将 /v2/api-docs 生成ASCIIDOC文件; •使用 asciidoctor-maven-plu... 阅读详情

前言

通过之前的两篇关于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之外,还有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的也是单一的。

通过 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目录下获得如下内容:生成confluence的代码片段:

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

 

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

 

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

 

代码示例

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

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

 

参考资料

 

Springcloud整合Swagger以及生成静态文档 1.添加依赖 <!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </depen 阅读详情

相关推荐

swagger静态部分文件打包

swagger静态部分文件打包,用于swagger的页面接口展示

Swagger文档生成操作SOP

Swagger文档生成操作SOP

笛卡尔的梦博客 496

使用 ANSYS AEDT(双向耦合)对高功率射频同轴滤波器进行热分析

使用 ANSYS HFSS,可以精确计算 EM 损耗,然后将其导入 ANSYS 热分析并使用 ANSYS Icepak CFD 求解器进行仿真,以帮助工程师解决最复杂的热挑战,并预测其设计在温度变化下的表现。然后,RF 损耗将与 ANSYS Icepak CFD 求解器耦合,以执行热分析,包括传热的传导、对流和辐射模式,并计算温度曲线。在此演示中,我们将仿真下面的 RF 同轴滤波器,并计算由于所用材料的有限电导率和介电损耗而导致的 RF 传导损耗。设置 HFSS 设计后,我们可以开始 HFSS 仿真。

jkh920184196的博客 1052

Swagger自动生成API文档

Swagger自动生成API文档

qq_39725573的博客 653

让AI稳定生成流程图:基于Skill与Mermaid的工程化实践

流程图是软件工程中沟通业务逻辑的通用语言,但其绘制与维护却长期依赖手工工具,导致文档更新滞后、协作成本高。随着大语言模型技术的成熟,自然语言生成代码已成为可落地的技术路径,而Mermaid作为一款文本化图表语法,凭借其可版本管理、可自动渲染和可嵌入文档的优势,正逐步取代传统绘图工具。要让AI稳定输出合格的流程图,关键在于为模型定义一套清晰的Skill规则,约束输入结构、处理逻辑和输出格式。本文从流程图的工程痛点出发,介绍如何利用大模型将自然语言描述转化为结构化文本,再通过Mermaid CLI渲染成可视化图

weixin_42548782的博客 314

提升RAG效果:为何 JSON 格式远胜 Markdown?

在构建强大的 RAG (检索增强生成) 系统时,文档解析是至关重要的第一步。它直接影响着后续的检索效率和生成质量。在众多文档格式中,JSON (JavaScript Object Notation) 格式正逐渐展现出其相对于传统 Markdown 格式的巨大优势。本文将深入探讨 JSON 在 RAG 系统文档解析中的卓越之处,并结合具体案例,让你理解为何 JSON 才是构建下一代智能应用的更优选择。RAG 系统的核心目标是让模型能够利用外部知识库,生成更精准、更贴合实际的答案。

simoncool23的博客 2719

使用swagger配置api文档,接口的访问路径和实际的有差别的解决办法

在swagger ui的页面上有: Base URL: 如果没有特别设定,那么显示的就是服务器的地址。接口的测试的url是由Base URL +接口的path。一般情况下是没有问题的。但是我这边代码部署到服务器后,访问地址变成了 :服务器的地址+项目name,这样的话,base Url显示其实就有问题了,少了项目name。同时,接口的测试url也会错误,缺少项目name。 解决一: ...

java_OnTheWay_kouhao的博客 2万+

【算法设计与分析】期末复习题(超详细)

刚刚整理了一下电脑的文件,发现了这份上学期的算法设计与分析期末复习题,有需要的文后自取。

a1234567822的博客 6617

FastAPI给docs/配置自有域名的静态资源swagger-ui

2. 安装插件fastapi-cdn-host(只适用0.100以上版本的fastapi,旧版本请自行参考官网示例)附:如果还想修改网站ico,可以传入favicon_url参数。

jaket5219999的博客 1387

使用Google Earth Engine(GEE)的Python API,您可以将经纬度坐标转换为Landsat影像的路径/行号

使用Google Earth Engine(GEE)的Python API,您可以将经纬度坐标转换为Landsat影像的路径/行号。在这个示例中,我们选择了一个位于加利福尼亚州旧金山市附近的点,其经度为-122.084,纬度为37.421998。首先,我们需要导入必要的库和模块。接下来,我们定义一个函数,该函数将接收经度和纬度作为输入,并返回对应的Landsat路径/行号。最后,我们提取路径和行号的值,并将它们作为结果返回。现在,我们可以使用这个函数来获取特定点的Landsat路径/行号。

VwajAlgorithm的博客 351

RK3588 平台部署实战:OpenCV + LibTorch + FFmpeg 环境搭建与深度学习推理全流程解析

现在,你已经掌握了在RK3588上搭建OpenCV+LibTorch+FFmpeg环境的完整流程,也完成了深度学习模型的部署测试。不妨从一个具体的应用场景入手(如检测自家宠物的品种),亲手打造属于你的第一个边缘智能应用——当你看到模型在RK3588上精准输出结果时,你会发现:嵌入式深度学习的门槛,其实并没有想象中那么高。这些依赖是编译OpenCV、FFmpeg的基础,安装过程中若提示权限不足,可在命令前加。若能输出预测的类别索引,则说明环境搭建成功,模型推理流程通畅。文件,实现模型加载、图像预处理与推理。

FJN110的博客 538

FastApI接口文档无法访问

python中Fast API的使用教程, 接口文档无法访问的三种处理方式

平时不搬砖的博客 3874

还在用 RaiDrive/Rclone 挂载网盘?教您使用Windows 原生 WebDAV 丝滑直连 AList/Openlist,让你的网盘秒变本地硬盘!

网盘文件分散管理?😩 别再依赖第三方工具了!本文教你如何在 Windows 下,利用原生 WebDAV 功能,将 Openlist 网盘直接映射为本地硬盘!💻 操作简单,告别繁琐,让你的云端文件像本地文件一样丝滑!🚀 轻松实现高效管理,快来体验吧!

XiaoqiangClub的博客 2981

swagger静态文档生成

swagger静态文档生成 有时候给接口文档的时候不能直接给个URL,这可能因为没部署上服务器,亦或是内网的限制. 这时对方需要一个HTML或者是个PDF静态文档,本来想着在swagger网址那里Ctrl+S保存下来发过去就行了,结果这样保存的文档根本不能看. 调研后发现,可以通过springfox-staticdocs组件生成swagger静态文件,然后通过maven组件根据静态文件生成HTML...

asd765028286的博客 3467

【Unity实战篇 】| 游戏中实现镂空遮罩效果【矩形、圆形镂空遮罩】

本文来写一下怎样在Unity中完成一个 镂空遮罩 的效果。 镂空遮罩 比较常用的有两种:矩形镂空遮罩、圆形镂空遮罩。 镂空遮罩 在游戏中常被当做新手引导必备的内容,可以给玩家更多不一样的体验。 下面就一起来看一下怎样做出这种效果吧!

努力前行,总会成为自己心中的那道光 1万+

假人有限元模型

假人模型,车辆碰撞假人有限元模型,适合做乘员安全的研究者利用

生成Swagger2静态文档

生成Swagger2静态文档 swagger文档每次都需要开启项目才能使用。不方便传阅。目前通过swagger2markup可以将swagger导出为markdown,asciidoc等。 swagger2markup 这个项目是在github上的 https://github.com/Swagger2Mark...

sias1991的专栏 4750

C# WinForm 基于DirectShow.dll编写的程序,可边预览边保存视频,音频和图片

基于微软的DirectShow.dll的二次开发1.自动识别连接的摄像头跟麦克风且可以对其进行选择(默认选中第一个)2.可录制wmv和avi两种格式的视频并且都带有音频,avi可以录制的分辨率和帧数进行选择,wmv默认进行了淸晰度优化如不喜欢可去除代码中有相关提示3.可在预览点开之后进行拍照,也可边录制视频边拍照4.添加了视频和音频的压缩功能(酌情使用)这次二次开发发现C#对DirectShow的相关信息太少,这次做完也不敢藏私共享出来,还望大家指正

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

前言 通过之前的两篇关于Swagger入门以及具体使用细节的介绍之后,我们已经能够轻松地为Spring MVC的Web项目自动构建出API文档了。如果您还不熟悉这块,可以先阅读: Spring Boot 2.x基础教程:使用Swagger2构建强大的API文档 Spring Boot 2.x基础教程:Swagger接口分类与各元素排序问题详解 在这两篇文章中,我们构建的文档必须通过在项目中...

程序猿DD 2227

Camera2Demo

在Camera2 的基础上进行封装,使得Camera2一堆初始化逻辑与Activity分离,降低耦合度,完成预览拍照并保存的操作

大中型超市收银系统(可直接运行)

光步前台收银系统系统功能:商品销售、商品退货、挂单、收银员权限、会员销售、单品取消、整单取消、商品查询、脱机销售、脱机数据上传,基本资料下载,开钱箱、小票打印、收款结算,支持多币种付款方式(现金、储值卡、礼券、微信等),支持多种促销。运行环境:.net 4.0登陆信息用户名:1001 密码:123456内置商品信息,商品编码可输入00001000 - 00010000,测试效果相关功能键F5 结算 F9挂单 F11商品查询 F8退货 Insert单品取消 Del整单取消 F12开钱箱F2 会员 Ctrl+Z退出系统 Home 锁屏 相关源码待公开

API文档离线访问:生成静态Swagger UI文件

当你在没有网络连接的环境下开发,或者需要将API文档部署到内网服务器时,动态生成的Swagger UI可能无法正常工作。本文将介绍如何使用Javalin框架生成可离线访问的静态Swagger UI文件,让你随时随地查阅API文档。 ## 准备工作 在开始之前,请确保你的项目中已经集成了Swagger相关依赖。如果你使用的是Maven,可以在`pom.xml`中添加以下依赖: ```xml ...

gitblog_00323的博客 983

[Swagger] 利用Gradle插件解析 swagger.json 并生成静态接口文档

[capsule-static-doc] 利用Gradle插件解析 swagger.json 并生成静态接口文档 利用Gradle插件解析 swagger.json 并生成静态接口文档 目录结构 |- capsule-static-doc |- docs |- asciidoc |- api |- index.doc ...

架构探险之道 3000

Swagger注解生成Rest Api文档 并生成静态文档

Swagger注解生成Rest Api文档 1、添加配置类 @Configuration //spring boot配置注解 @EnableSwagger2 //启用swagger2功能注解 public class Swagger2Config extends WebMvcConfigurationSupport { @Bean public Docket createRe...

Adonis_D_Gogh的博 客 1377

jeesite如何配置swagger_Spring Boot 2.x基础教程:Swagger静态文档的生成

前言通过之前的两篇关于Swagger入门以及具体使用细节的介绍之后,我们已经能够轻松地为Spring MVC的Web项目自动构建出API文档了。如果您还不熟悉这块,可以先阅读:Spring Boot 2.x基础教程:使用Swagger2构建强大的API文档Spring Boot 2.x基础教程:Swagger接口分类与各元素排序问题详解在这两篇文章中,我们构建的文档必须通过在项目中整合swagge...

weixin_39914868的博客 81

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

点击蓝色“程序猿DD”关注我回复“资源”获取独家整理的学习资料!作者 | 翟永超来源 |didispace.com/spring-boot-learning-21-2-...

程序猿DD 675

swagger2静态API文档生成

swagger2静态API文档生成 swagger2静态API文档生成 基本上按照上面链接的文章指导就能做好这个静态文档生成,需要注意的是,class上的标签 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT) 需要加上你自己项目的启动类 @SpringBootTest(webEnvironme...

黑橙子君的博客 1245

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

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

weixin_32818917的博客 250
上一篇: 使用Swagger2构建强大的API文档
下一篇: Log4j2中RollingFile的文件滚动更新机制
淋雨一直走啊
博客等级 码龄11年 39粉丝 46原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值