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

Question

我获得了一个Swagger API，请求体定义为

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

编写API的程序员正在度假，无法联系到。我无权访问API代码。一般来说，无论如何都要询问api以确定“string”的有效值是什么？或者我是否必须等待该人回到办公室？

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

如果答案是我运气不好（我强烈怀疑这是真的）是否有一种方法可以建议作者在API中记录“字符串”的有效语法，以便下一步人不会经历这个？

Answer 1

听起来您已经找到了通往Swagger-UI的方式，显示了API文档并进行了互动＆＃34;尝试一下＆＃34;纽扣。

最有可能的是，API并没有像您需要的那样彻底记录。但是，您可以从Swagger规范中找到更多信息。您可以采取以下几点来深入挖掘：

查看请求模型

在Swagger-UI中，单击＆＃34;模型＆＃34;操作标题中的选项卡：

如果开发人员提供了属性级别描述，则会显示有关请求结构的其他详细信息。错误的＆＃34;模型架构＆＃34;默认情况下显示的选项卡实际上是消息结构的自动生成示例;如果您正在寻找详细的请求文档，那就没用了。

检查Swagger来源

您可以检查填充Swagger-UI的Swagger源规范。尝试使用＆＃34;查看源＆＃34;在浏览器中执行命令，并查找SwaggerUi对象构造函数。它看起来像这样：

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

按照指定的url查找源Swagger规范，并查看是否有更多可用信息。你不太可能在Swagger-UI中显示更多内容，但它值得一试。

请注意，SwaggerUi构造函数的另一种形式没有使用url属性。相反，它使用spec属性，其值为（big！）JSON对象。您可以将该对象复制粘贴到Swagger或JSON编辑器中（以便于使用自动格式，语法着色等进行阅读），并查看是否还有其他信息。

  

如果答案是我运气不好（我强烈怀疑这是真的），我可以建议作者记录＆＃34;字符串＆＃34;的有效语法。在API中，以便下一个人不通过这个？

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