When you control versions of my API, how do I maintain swagger documentation if I use the same DTO?

Question

It was recommended that DTO defensive development be maintained over time at version endpoints, but it’s hard for me to do without losing what I consider to be one of the useful functionality provided by ServiceStack.

I am currently using ServiceStack v3, but you can upgrade to v4 if necessary.

When implementing my service, I can specify several Get () implementations with different contracts, and ServiceStack displays the data coming in accordingly.

Works:

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

Also works:

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

Does not work:

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

This case does not work to such an extent that all POSTs that come through this service are mapped to the v1 contract, although the fields do not match. Even the swagger documents demonstrate the incorrect properties of v1, but the correct summary / notes from v2 DTO.

I would like to have a separate DTO for each major version of this endpoint for several reasons:

• Courage . Swagger documents created from a DTO with many fields can be confusing for end users of public APIs. How does the user know which fields are for the version of the endpoint that they want to use? I can document this for each field, but I think it’s easier to show the end user only the fields that they like at that time. Different clients will use v2, not knowing that v1 exists.

• Validation ServiceStack provides validators for each type. This is fine, except that if my required DTO fields can change over time, I cannot continue to use the same validator without any special shell. Maybe this is an acceptable loss?

• Outdated . After the specified time, v1 will become obsolete. v1 is a legacy endpoint implementation, before version control was implemented, and before there were agreed contracts between objects (for example, using "Name" versus "Name", "TypeId" and "Type"). The development of DTO over time after that seems more reasonable, but while v1 exists, endpoints are limited to decisions that developers made, perhaps a decade ago.

After reading this several times, I think that perhaps I should create separate services to support older functions.

The key differences between the versions of my endpoints are:

• permissions
• field names
• organization and display of fields (for example, deleting nested objects)
• implementation details (e.g. how many results are returned by default)

Should I consider splitting my versions into separate services? Should I load one DTO with all fields and just outline the supported version for each property?

Answer 1

I would strongly recommend that you do not use multiple versions of the same DTO request in the same service, instead you should do your DTO protection so that your DTO request can support multiple versions. This is especially bad when trying to support multiple versions of the same Service in a statically typed language that causes a lot of friction, duplicate code, maintenance, etc.

If you must support different versions, I would recommend maintaining and hosting different branches and have a reverse proxy to redirect requests /v1/ and /v2/ API to old and new instances of ServiceStack. Thus, as soon as all clients switch from v1, you can reset it, and your v2 will be clean, without an outdated v1 crack that infects the current code base. But my recommendation is to protect the same DTO request that you do not need to support multiple versions, the design based on ServiceStack messages makes this a lot easier. It will also reduce confusion, both inside and out, trying to support multiple versions, confusing the developers who support the Service, and everyone who consumes them.

In ServiceStack, each type of DTO request must be unique and have only one implementation, however, most metadata services require that the name of the DTO request is unique, and many languages ​​in Add ServiceStack Reference also require that all DTOs be unique, which is our recommendation. If you absolutely must have different types with different versions, add the version to the DTO request, for example. GetEntitiesV1 and GetEntitiesV2 - these names will be hidden from users using published custom routes.

ServiceStack Swagger support has seen many updates in v4, if you see problems in v3, you can use Free Quotas in version 4 to see if the problems have been fixed.