获取有关请求正文中字符串的预期语法的信息

Question

我得到了一个 Swagger API，请求正文定义为

{
  "SqlFilterList": "string",
  "SubjectKey": 0,
  "SubjectCwaListingKey": 0
}

编写 API 的程序员正在休假，无法联系到。我无权访问 API 代码。一般来说，是否有询问 api 以确定 "string" 的有效值可能是什么？还是必须等对方回来？

我已经通过 URL 查看了 API 的文档（这就是为什么我知道它需要一个字符串），我搜索了 Swagger website 并搜索了问题在 Whosebug 中带有标签 [swagger]，但没有发现任何东西。

如果答案是我运气不好（我强烈怀疑这是真的），我是否可以建议作者记录 "string" 的有效语法 API 这样下一个人就不会经历这个？

Answer 1

听起来您已经找到 Swagger-UI，显示 API 文档和交互式 "try it out" 按钮。

最有可能的是，API 没有像您需要的那样完整地记录下来。但是您有可能从 Swagger 规范中找到更多信息。您可以做几件事来深入挖掘：

查看请求模型

在Swagger-UI中点击"model"选项卡中的操作header:

如果开发人员提供了 property-level 描述，这将显示有关请求结构的其他详细信息。默认显示的错误命名的 "model schema" 选项卡实际上是消息结构的 auto-generated 示例；如果您正在寻找详细的请求文档，则用处不大。

检查 Swagger 源代码

您也许能够检查填充 Swagger-UI 的 Swagger 源规范。尝试在浏览器中使用 "view source" 命令，然后查找 SwaggerUi object 构造函数。它看起来像这样：

var swaggerUi = new SwaggerUi({
  url: 'http://petstore.swagger.io/v2/swagger.json',
  dom_id: 'swagger-ui-container'
});

按照指定的 url 查找源代码 Swagger 规范，并查看是否有任何进一步的信息可用。您不太可能在那里找到比 Swagger-UI 中显示的更多的内容，但值得一试。

请注意，还有另一种形式的 SwaggerUi 构造函数不使用 url 属性。相反，它使用 spec 属性，其值为（大！）JSON object。您可以 copy-paste 那个 object 进入 Swagger 或 JSON 编辑器（使用 auto-format、语法着色等更容易阅读）并查看那里是否有任何进一步的信息。

If the answer is that I am out of luck (which I strongly suspect to be true) is there a way that I can suggest to the author to document the valid syntax of the "string" in the API so that the next person doesn't go through this?

希望 API 开发人员通过电子邮件或支持网站提供了反馈渠道。可能有一些 API 文档小部件直接包含反馈或讨论，但 Swagger-UI 目前没有，AFAIK。

获取有关请求正文中字符串的预期语法的信息

Get information about the expected syntax of a string in the request body

swagger

swagger-editor