解决Swagger UI示例值显示"string"的问题

最近在使用ObjectScript生成JSON接口文档时，遇到了一个奇怪的问题：

  • 生成的JSON数据是正常的。

  • 但Swagger UI的Example Value却显示为"string"，而不是预期的JSON结构。

经过一番排查，我发现问题的根源在于Swagger UI的版本问题，并成功找到了解决方案。这里分享我的思考过程，希望能帮到有类似困扰的朋友。

排查过程

1. 确保生成的JSON数据正确

最开始，我怀疑是代码逻辑有误，导致生成的JSON格式不对。然而，当我把生成的JSON复制到Swagger Editor中时，发现它能正确解析，这说明JSON本身是正确的。

这让我意识到，Swagger UI可能是自动补全了正确的 OpenAPI/Swagger 版本信息，从而正常显示JSON数据。

2. 怀疑Swagger UI版本问题

既然JSON数据是正确的，那问题可能出在Swagger UI的版本上。我回顾了自己的环境，发现Swagger UI的版本是5.11.0。

    <head>

        <meta charset="utf-8"/>

        <meta name="viewport" content="width=device-width, initial-scale=1"/>

        <meta name="description" content="SwaggerUI"/>

        <title></title>

        <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css"/>

    </head>

于是，我尝试直接修改生成的HTML文件，将Swagger UI的版本从5.11.0升级到5.20.0（即最新版本），然后重新加载页面，结果问题完美解决！

3. 发现官方修复记录

随后，我在Swagger UI的官方Release Notes中找到了相关修复记录。

原来，在5.11.10版本中，Swagger UI修复了这个Bug。

这也进一步验证了我的猜测：问题并非出在我的代码，而是Swagger UI在旧版本中的Bug导致Example Value无法正确显示。

经验总结

  1. 不要太相信AI工具。我问了gpt4和claude3.5都3.7，一直给我乱改代码，找不到原因。
  2. 遇到问题，思路要开放。不要一开始就怀疑自己的代码，可能是外部工具或库的问题。
  3. 检查工具版本。当出现未知问题时，尝试更新到最新版本，或查阅官方Release Notes，可能Bug早已被修复。
  4. 直接修改生成的HTML。在无法确定问题来源时，直接编辑最终生成的文件，能更直观地测试不同版本的影响。

希望这篇文章能帮助到有类似困扰的朋友，也欢迎大家分享自己的调试经验！

Swagger OpenAPI Schema 为空时 Example Value 显示 "string" 的原因及解决方案的更多相关文章

  1. asp:Repeater数据源为空时处理方式

    当Repeater的数据源为空时,会显示空白,界面不友好,以下方式可以简单处理. <asp:repeater runat="server" id="rplist2& ...

  2. Swagger/OpenAPI By Swashbuckle在NetCore 3.1中较NetCore 2.2使用的注意事项及入门

    方案选择 使用Web API时,了解其各种方法对开发人员来说可能是一项挑战. Swagger也称为OpenAPI(Open Application Programming Interface,开放应用 ...

  3. 服务器通信REST、gRPC，Swagger/OpenAPI

    服务间的通信方式是在采用微服务架构时需要做出一个最基本的决策.默认的选项是通过 HTTP 发送 JSON,也就是所谓的 REST API.我们也是从 REST 开始的,但最近我们决定改用 gRPC. ...

  4. 服务器通信REST、gRPC，Swagger/OpenAPI，Consul

    服务间的通信方式是在采用微服务架构时需要做出一个最基本的决策.默认的选项是通过 HTTP 发送 JSON,也就是所谓的 REST API.我们也是从 REST 开始的,但最近我们决定改用 gRPC. ...

  5. VB6.0中，DTPicker日期、时间控件不允许为空时，采用文本框与日期、时间控件相互替换赋值（解决方案）

    VB6.0中,日期.时间控件不允许为空时,采用文本框与日期.时间控件相互替换赋值,或许是一个不错的选择. 实现效果如下图: 文本框txtStopTime1 时间框DTStopTime1(DTPicke ...

  6. [WPF]ComboBox.Items为空时，点击不显示下拉列表

    ComboBox.Items为空时,点击后会显示空下拉列表: ComboBox点击显示下拉列表,大概原理为: ComboBox存在ToggleButton控件,默认ToggleButton.IsChe ...

  7. esayUi中datagrid中json串为空时，显示上一次数据的解决方法

    function initSearchProject(startDate,finishDate,flag) {        $("#finishDate").val(finish ...

  8. easyUI draggable插件使用不当，导致拖动div内部文本框无法输入；设置echarts数据为空时就显示空白，不要动画和文字

    先上一个Demo <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://ww ...

  9. IE9或以上的浏览器flash值为空时，导致domready不触发

    在前些时间开发中遇到一个问题当flash值<param name="movie" value=""/>为空时,IE版本>=9不会触发domre ...

  10. 如何让listview列表为空时显示提示

    先在布局文件中声明一个TextView,再设置listview.setEmptyView(TextView).这样当listview中的数据为空时就会列表的位置就会显示textviw中的提示.

随机推荐

  1. cocos2d 的故事

    https://en.wikipedia.org/wiki/Cocos2d The history of Cocos2d in a glimpse – RETRO.MOE http://los-coc ...

  2. HTMLreport报告（五） -- 测试报告中添加截图

    一.需求痛点 HTMLreport报告没有截图 二.实现办法 1.思路:使用viewer.js图片查看器,用cdn:后端部分用 unittest.test_result中的内容 2.实现步骤 1)vi ...

  3. Qt视频监控系统一个诡异问题的解决思路（做梦都想不到）

    一.前言 由于Qt版本众多,几百个版本之间存在不兼容的情况,为此如果要兼容很多版本,没有取巧的办法和特殊的捷径,必须自己亲自安装各个版本编译运行并测试,大问题一般不会有,除非缺少模块,小问题还是不断有 ...

  4. Qt编写安防视频监控系统26-硬件加速

    一.前言 硬件加速这个功能在一年多以前就已经具备,当时对两个内核一个是ffmpeg内核.一个是vlc内核都做了对应的接口函数,只是当时为了简单没有在系统设置中做出接口,vlc做硬件加速不用自己写代码实 ...

  5. Qt编写项目作品35-数据库综合应用组件

    一.功能特点 同时支持多种数据库比如odbc.sqlite.mysql.postgresql.sqlserver.oracle.人大金仓等. 一个数据库类即可管理本地数据库通信,也支持远程数据库通信等 ...

  6. WxPython跨平台开发框架之复杂界面内容的分拆和重组处理

    复杂界面内容的分拆和重组处理是现代软件开发中常见的做法,尤其在开发大型应用程序时,可以大幅提升开发效率.可维护性和用户体验.通过将复杂的界面内容分拆成更小的模块,每个模块都专注于单一功能或组件,代码更 ...

  7. 墨卡托及Web墨卡托投影解析

    Google Maps.Virtual Earth等网络地理所使用的地图投影,常被称作Web Mercator(Web墨卡托投影)或Spherical Mercator(球面墨卡托投影),它与常规墨卡 ...

  8. vue3.0实现炫酷的随机验证码功能

    先上图 接下来楼一眼实现代码 这里说明一下,我用到了vue3.0,vant3.0以及阿里图标,vant 很人性化针对vue3.0新出了个vant3.0版本,阿里则是适配vue3.0的.我们将verif ...

  9. ABC 386 (A~F)

    赛时做的,结果一直在卡D题.打得很失败的一场. ABC 略. D 题意可以转化为:给定\(m\)个黑色或白色的格子,其中: 每个黑色格子和\((1,1)\)作为对角线顶点,构成一个黑色矩形 每个白色格 ...

  10. 如何快速的开发一个完整的iOS直播app(推流篇)

    开发一款直播app,肯定需要流媒体服务器,本篇主要讲解直播中流媒体服务器搭建,并且讲解了如何利用FFMPEG编码和推流,并且介绍了FFMPEG常见命令. 效果 一.安装Homebrew Homebre ...