是否存在将OpenAPI3转换为Restdocs(adoc)格式的可行解决方案？

Swagger2Markup 已停止功能迭代，不支持OpenAPI3是已知的长期问题，目前经过生产验证的可行方案主要有三类：

• OpenAPI Generator 构建插件
  这是目前多数从Swagger2Markup迁移的团队的首选方案，Maven、Gradle均提供对应插件，生成目标选择asciidoc即可输出适配Restdocs规范的adoc文档。插件支持自定义模板、接口过滤、内嵌响应示例，生成的文档结构和Swagger2Markup的输出逻辑高度对齐，迁移时只需要替换插件配置、调整少量自定义模板参数，就能得到和之前一致的文档效果，生成的片段可以直接被Restdocs的include指令引入，和测试生成的请求样例、手写业务说明拼接成完整文档。
• Spring 栈原生集成方案
  如果是基于SpringBoot、SpringCloud的Java项目，可以直接用springdoc-openapi抓取运行时的OpenAPI3结构，配合spring-restdocs-asciidoctor扩展，在单元测试阶段直接生成adoc片段，不需要做离线格式转换。生成的内容天然对齐Restdocs的字段约束、请求响应snippet格式，还能自动同步代码里的参数校验注解、接口路径变更，从根源避免文档和代码逻辑不一致的问题。
• 轻量命令行转换工具
  如果是非Java技术栈，或者需要在CI流程中独立执行文档转换，可以选择widdler这类轻量命令行工具，不需要绑定项目构建流程，支持自定义章节排序、隐藏内部接口、导入外部Markdown格式的接口备注，输出默认适配Restdocs的adoc排版规范，不需要额外做格式调整。

迁移提示：如果之前基于Swagger2Markup做过深度的模板自定义，只需要把原有模板的语法替换成对应工具的模板语法即可，绝大多数普通场景不需要额外调整排版配置，最终生成的HTML/PDF静态文档效果和OpenAPI2版本基本无差异。

内容的提问来源于stack exchange，提问作者tofan