ServiceStack + Swagger-UI [Api]属性用法

Question

我一定是愚蠢的，但我无法弄清楚[Api]属性的实际用途对ServiceStack's SwaggerFeature的影响。

不标记[Api]似乎不会影响api是否出现在Swagger中，并且在使用它时无法找到在任何地方呈现的描述，如[Api（“服务描述”）]

我的用法是这样的：

[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

Answer 1

ApiAttribute不再用于任何与Swagger相关的功能。我能找到的唯一用途是metadata page。

使用RouteAttribute描述服务端点是在Swagger中记录路线的正确方法。您可以浏览SwaggerApiService和its unit ests的来源，详细了解哪些属性等可用于在Swagger中记录您的API。

修改

实际上，正如评论中所提到的，ApiAttribute Description值正在返回给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客户端并存储在swagger.js中的SwaggerResource对象中，但似乎不会以任何方式显示在屏幕上。至少使用ServiceStack使用的当前版本的Swagger。

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