在 API-Explorer/Swagger 中描述响应对象答案

【问题标题】：Describing response object in API-Explorer/Swagger在 API-Explorer/Swagger 中描述响应对象
【发布时间】：2013-01-21 20:30:21
【问题描述】：

我正在使用Restler 3's API-Explorer，它是Swagger-UI 的一个分支，我想知道是否有人找到了一种有效的方法来记录/描述API 返回的响应JSON 对象。显然，当您以交互方式试用 API 时，其中的一些——以“字里行间”的方式——是可用的，但我想要一些更详细地指示响应结构的方式。有没有人为此提出任何建议？

【问题讨论】：

标签： php restler swagger

【解决方案1】：

您可以使用@return PHPDoc 注释来做到这一点。

例如，看看explorer 中的Rate Limiting Example

GET authors.json/{id}

您会发现响应信息列表

Author ( name: string, email: string )

它来自以下设置为返回类型的类

<?php
/**
 * Dummy class, used only for creating swagger spec model (json schema)
 * look at the generated resources json to understand
 */
class Author
{
    public $name='Name';
    public $email='name@domain.com';
}

【讨论】：

很好的例子。这正是我想要的！
由于某种原因，我自己的版本没有公开响应信息（它也没有显示变量类型信息）。可能是我搞砸了。有什么想法吗？
顺便说一句，我有来自 Restler-API-Explorer (0d79cd8) 的“主”分支的最新 git 版本。不过，我对 git 有点陌生，因为我将它分叉并通过远程“上游”保持对您的存储库的引用，所以我有点担心当我合并我的更改时我做了一些愚蠢的事情。我的更改非常基本.
我去看看，同时使用示例自带的资源管理器
是的，我昨晚想到了这个想法，它确实改进了一些东西，但它并不完美......类型出现了，但它们都被列为“字符串”并且 BODY 变量的 JSON 预填充没有发生。