title: When versioning my API, how do I maintain swagger documentation if I use the same DTO?
body: <p>It has been recommended to favor <a href="https://stackoverflow.com/questions/12400071/servicestack-restful-resource-versioning/12413091#12413091">defensively evolving a DTO over time</a> when versioning endpoints, but I'm finding it difficult to do without losing what I consider some key beneficial functionality provided by ServiceStack.</p>
  
  <p>I am currently using ServiceStack v3, but can upgrade to v4 if/when necessary.</p>
  
  <p>When implementing my Service, I can specify multiple implementations of Get() with different contracts, and ServiceStack maps the data coming in accordingly.</p>
  
  <p>Works:</p>
  
  <pre><code>public object Get(EntityBrowse) { ... } // returns multiple of a single entity
  public object Get(Entity) { ... } // returns a single entity
  </code></pre>
  
  <p>Also Works:</p>
  
  <pre><code>public object Get(Contracts.v1.Entity) { ... } 
  public object Get(Contracts.v2.Entity) { ... }
  </code></pre>
  
  <p>Does not work:</p>
  
  <pre><code>public object Post(Contracts.v1.Entity) { ... }
  public object Post(Contracts.v2.Entity) { ... }
  </code></pre>
  
  <p>This case doesn't work to the point where all POSTs that come through this service are mapping to the v1 contract, even though the fields don't match. Even the swagger docs are showing the wrong v1 properties, but the correct summary/notes from the v2 DTO.</p>
  
  <p>I would like to have a separate DTO for each major version of a given endpoint for a few reasons:</p>
  
  <ol>
  <li><p><strong>Swagger</strong>. Swagger docs generated from DTOs with a lot of fields can be confusing to the end users of public APIs. How does the user know which fields are for the version of the endpoint they want to use? I could document this per field, but I think it is easier to show the end user only the fields they care about at the time. Different customers will use v2 without ever knowing v1 existed.</p></li>
  <li><p><strong>Validation</strong>. ServiceStack provides validators per Type. This is perfect, except that if my DTO's required fields may drift over time, I can't continue using the same validator without some special casing. Maybe this is an acceptable loss?</p></li>
  <li><p><strong>Deprecation</strong>. After a given time, v1 will be deprecated. v1 represents the legacy implementation of the endpoint, before there was versioning, and before there were consistent contracts between entities (eg, using "Name" vs "Title", "TypeId" vs "Type"). Evolving a DTO over time after this seems more reasonable, but while v1 exists, the endpoints are restricted by the decisions developers made possibly up to a decade ago.</p></li>
  </ol>
  
  <p>After reading over this a few times, I'm thinking that maybe I should be creating separate services to support older functionality.</p>
  
  <p>The key differences between versions of my endpoints are:</p>
  
  <ul>
  <li>permissions</li>
  <li>field names</li>
  <li>organization and mapping of fields (eg, removal of nested objects)</li>
  <li>implementation details (eg, how many results are returned by default)</li>
  </ul>
  
  <p>Should I consider breaking my versions out in to separate services? Should I load up a single DTO with all the fields and just outline the supported version per property?</p>