ServiceStack在元数据,OpenAPI和Swagger之间的混淆

时间:2017-08-16 21:02:03

标签: c# servicestack

我正在研究使用ServiceStack实现的API服务器的文档。我有几个问题。如果它更有意义,我可以将它们移到单独的帖子中。

  1. IgnoreDataMember 在多个地方被提及作为从元数据隐藏DTO属性的方法,但如果您将消息发布到队列,那么这不是一个选项,因为它通过序列化工作并且它会跳过这些字段...

  2. 排除属性 [排除(Feature.Metadata)] 应该从数据库页面中隐藏DTO。虽然它适用于顶级类,但它不会过滤掉基类的属性。换句话说,如果将MyBaseDto标记为exlude,但MyEndpointDto继承自MyBaseDto,则会显示两个类的属性。这是一个错误吗?

  3. 从元数据中删除服务的效果非常好,但我没有看到如何从Swagger / OpenAPI中删除它们。我可以实现 OperationFilter 回调,但没有明显的方法来实际删除任何东西。如果我使用 ResourceFilterPattern regex属性,它将由DTO工作,而不是路由。我想删除任何以/ internal开头的路线。

  4. OpenApiFeature和SwaggerFeature的 LogoUrl 属性似乎实际上不会影响任何地方的页面。还有其他步骤吗?

  5. 在Swagger UI页面上,为什么每条路线都包含文字“XX未定义!”我不确定它应该是什么样的。

  6. 我需要帮助了解OpenAPI和Swagger如何结合在一起。为什么它们是两个独立的功能?如果我只是添加OpenAPI功能,我仍然可以调出Swagger UI。 Swagger功能带来了什么?

1 个答案:

答案 0 :(得分:2)

ServiceStack的Swagger FeatureOpen API之间的区别在于,Swagger功能实现了较旧的Swagger 1.2规范,其中Open API实现了从Swagger重命名的较新Swagger 2.0 spec 。如果您不确定使用哪个,请使用较新的Open API。

Swagger UI只是UI和ServiceStack捆绑了Swagger UI的一个版本,它与较旧的Swagger 1.2规范以及较新的Open API 2.0规范一起使用。

[Exclude(Feature.Metadata)][ExcludeMetadata]按预期工作,在您希望从ServiceStack的元数据服务中排除的DTO上对其进行注释,该服务还会删除它们包含在返回的Swagger / Open API规范+ UI中

您可以使用ApiDeclarationFilter在返回之前修改整个OpenApiDeclaration,您可以通过从Paths词典和类型定义中删除路线来删除路线从Definitions字典中删除它们。您可以为missing features you want implemented提交其他功能请求。

已为Open API修复LogoUrl,我们还添加了LogoHref,因此您可以更改徽标转到的网址,默认情况下会刷新Swagger UI页面。此更改可从v4.5.13获得,现在为available on MyGet

Open API是规范Swagger UI是UI

Open API和Swagger插件的目的是实现Swagger规范,该规范是用于描述Service API的通用和机器可读的json格式。只有一个好处是通过捆绑与各自API版本一起使用的Swagger UI来提供ServiceStack提供的动态UI。实现Open API规范的其他目的包括启用generating a Azure AutoRest client之类的自动工具或将您的服务导入Azure's Management API