在对我的API进行版本控制时,如果使用相同的DTO,如何维护swagger文档？

Question

在版本化端点时,建议在一段时间内支持防御性地发展DTO,但我发现很难在不失去我认为ServiceStack提供的一些关键有益功能的情况下做到这一点.

我目前正在使用ServiceStack v3,但如果/必要时可以升级到v4.

在实现我的服务时,我可以使用不同的协定指定Get()的多个实现,并且ServiceStack相应地映射进入的数据.

作品:

public object Get(EntityBrowse) { ... } // returns multiple of a single entity
public object Get(Entity) { ... } // returns a single entity

还有效:

public object Get(Contracts.v1.Entity) { ... } 
public object Get(Contracts.v2.Entity) { ... }

不起作用:

public object Post(Contracts.v1.Entity) { ... }
public object Post(Contracts.v2.Entity) { ... }

这种情况不起作用,通过此服务的所有POST都映射到v1合同,即使字段不匹配.即使是昂首阔步的文档也显示错误的v1属性,但是来自v2 DTO的正确摘要/注释.

我想为给定端点的每个主要版本提供单独的DTO,原因如下:

1. 摇摇晃晃.从具有大量字段的DTO生成的Swagger文档可能会使公共API的最终用户感到困惑.用户如何知道哪些字段适用于他们想要使用的端点版本？我可以在每个字段中记录这个,但我认为向最终用户显示他们当时关心的字段更容易.不同的客户将使用v2而不知道v1存在.

2. 验证.ServiceStack为每个Type提供验证器.这是完美的,除非我的DTO所需的字段可能会随着时间的推移而漂移,我不能在没有特殊外壳的情况下继续使用相同的验证器.也许这是一个可以接受的损失？

3. 弃用.在给定时间之后,v1将被弃用.v1表示端点的遗留实现,在版本控制之前,以及实体之间存在一致的合同之前(例如,使用"Name"与"Title","TypeId"vs"Type").在此之后随着时间的推移演变DTO似乎更合理,但是当v1存在时,端点受到开发人员可能在十年前做出的决策的限制.

在阅读了几次之后,我想也许我应该创建单独的服务来支持旧功能.

我的端点版本之间的主要区别是:

• 权限
• 字段名称
• 组织和字段映射(例如,删除嵌套对象)
• 实现细节(例如,默认返回多少结果)

我应该考虑将我的版本分解为单独的服务吗？我是否应该在所有字段中加载单个DTO,并仅列出每个属性支持的版本？

Answer 1

我强烈建议不要在同一服务中使用同一请求 DTO 的多个版本，您应该对DTO 进行防御性版本控制，以便您的请求 DTO 可以支持多个版本。尝试用静态类型语言维护同一服务的多个版本尤其糟糕，这会导致很多摩擦、重复代码、维护等。

如果您必须维护不同的版本，我建议您维护和托管不同的分支，并使用反向代理将 API 请求重定向/v1/到/v2/新旧 ServiceStack 实例。这样，一旦所有客户都从 v1 迁移出来，您就可以放弃它，您的 v2 将变得干净，而不会遗留 v1 的缺陷，从而感染当前的代码库。但我的建议是防御性地对同一个 Request DTO 进行版本控制，这样您就不必维护多个版本，ServiceStack 基于消息的设计使这变得更加容易。它还将减少内部和外部的混乱，尝试维护多个版本会让维护服务的开发人员和使用它们的任何人感到困惑。

在 ServiceStack 中，每个请求 DTO 类型应该是唯一的，并且只有一个实现，但是大多数元数据服务也要求请求 DTO 名称是唯一的，并且“添加 ServiceStack 参考”中的许多语言也要求所有 DTO 都是唯一的，这是我们的建议。如果您绝对必须拥有具有不同版本的不同类型，请在请求 DTO 上附加版本，例如GetEntitiesV1-GetEntitiesV2这些名称将对使用您发布的自定义路由的用户隐藏。

ServiceStack 的 Swagger 支持在 v4 中进行了很多更新，如果您在 v3 中看到问题，可以使用v4 中的免费配额来查看问题是否已解决。