1

我一定很愚蠢，但我无法弄清楚 [Api] 属性的使用实际上对ServiceStack 的 SwaggerFeature做了什么。

不标记 [Api] 似乎不会影响 api 是否出现在 Swagger 中，并且在使用它时我找不到任何地方呈现的描述，例如 [Api("Service Description")]

我的用法是这样的：

[Api("Monkey Service Description")]
[Route("/zoo/monkey/{Id}", "GET", Summary = "Get MonkeyDocument by Id", Notes = "Returns a MonkeyDocument based on Id")]
public class GetMonkey : GetAnimal, IReturn<MonkeyDocument> // GetAnimal Has Id property
{
}

在 Swagger-UI 中，结果在展开时显示在页面上：

/zoo              Show/Hide List Operations Expand Operations Raw

 + GET /zoo/monkey/{Id}                  Get MonkeyDocument by Id
      Implementation Notes
      Returns a MonkeyDocument based on Id
4

1 回答 1

3

ApiAttribute不再用于任何与 Swagger 相关的功能。我能找到的唯一用法与元数据页面有关。

您使用RouteAttribute来描述服务端点是在 Swagger 中记录您的路由的正确方法。您可以浏览SwaggerApiService的源代码及其单元，以了解更多关于哪些属性等可用于在 Swagger 中记录您的 API。

编辑

实际上，正如评论中提到的，ApiAttributeDescription值正在返回给 Swagger UI 客户端。例如，从初始资源请求返回的 JSON 看起来像：

{
  "swaggerVersion":"1.1",
  "basePath":"http://localhost/api",
  "apis":[
     {"path":"/resource/zoo","description":"Monkey Service Description"}, ...
  ]
}

此特定description值与属性描述值分开Route，后者在 Swagger UI 中呈现并从单独的 Ajax 请求返回。描述ApiAttribute值虽然返回到 Swagger UI 客户端并存储在SwaggerResourceswagger.js 中的对象中，但似乎不会以任何方式显示在屏幕上。至少对于 ServiceStack 使用的 Swagger 的当前版本。

这是一个屏幕截图，显示了如何在给定 DTO 的元数据页面上使用 Api 和 Route 属性。我为同一个 DTO 类设置了两个路由来显示差异：

在此处输入图像描述

于 2013-10-18T12:16:55.160 回答