[Automated][tcgc] Document server URL template parameter API version detection (#4416)

Update versioning docs to explain that name-based API version detection
applies to both HTTP metadata parameters and server URL template
parameters declared in @server. This documents the fix from PR #4341
regression where server URL template params named apiVersion/api-version
were not recognized.

Also update knowledge base with lessons from PR #4398 feedback.

Resolve: #4404

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>

Author: 4 people

eng/scripts/doc-updater/knowledge/tcgc.md

@@ -143,6 +143,10 @@ namespace (@clientNamespace), naming (@clientName), overload, structure (@client
 - Don't add Spector specs for code-generation controls like @convenientAPI/@protocolAPI — they aren't testable at the HTTP wire level.
 - The `@deserializeEmptyStringAsNull` section was removed from 08types.mdx in feedback PR #4268. Don't re-add it unless specifically requested.
 - Spector response-as-bool spec needs BOTH a success (200) case AND a 404 case to be complete.
+- TypeSpec examples in docs with operations MUST include `@route` decorators to be valid TypeSpec (feedback PR #4398).
+- In @hierarchyBuilding language examples: each language handles inheritance differently. Python doesn't use real hierarchy (copies all props to each class). Go uses flat structs. C# and TypeScript use real inheritance. Java uses class inheritance.
+- C# property names that conflict with their enclosing class name should use a suffix (e.g., `CProperty` not `C` for a property in class `C`).
+- The "Body Model Properties Named apiVersion" section was removed from 10versioning.mdx during review (PR #4398) — don't re-add as a separate section. The behavior is covered implicitly by the main description.
 
 ## @responseAsBool Internal Design
 
@@ -171,4 +175,5 @@ namespace (@clientNamespace), naming (@clientName), overload, structure (@client
 - Readonly properties have Input flag stripped but other flags (Output, Json, Xml) still propagate through.
 - External types (via @alternateType with ExternalTypeInfo) block propagation of all non-External flags.
 - `@apiVersion(false)` prevents a parameter from matching to a client API version parameter, keeping it on the method.
-- Body model properties named "apiVersion" are NOT treated as API version params — only HTTP metadata params (header/query/path/cookie) are matched by name.
+- Body model properties named "apiVersion" are NOT treated as API version params — only HTTP metadata params (header/query/path/cookie) and server URL template parameters (from `@server`) are matched by name.
+- Server URL template parameters (declared in `@server` decorator's parameter model) named `apiVersion`/`api-version` are recognized as API version params, even with plain `string` type in versioned services.

eng/scripts/doc-updater/knowledge/tcgc.meta.json

@@ -1,6 +1,6 @@
 {
-  "lastCommit": "3c44dbcd32aa0bbe051f048c585dc84b6f7f37f0",
-  "lastUpdated": "2026-05-04T10:55:59.245Z",
+  "lastCommit": "5849136c72dc8034af0c6e6f0c44a2843bf2ef2e",
+  "lastUpdated": "2026-05-11T10:59:26.562Z",
   "analyzedPaths": [
     "packages/typespec-client-generator-core/src",
     "packages/typespec-client-generator-core/lib",

website/src/content/docs/docs/howtos/Generate client libraries/10versioning.mdx

@@ -829,7 +829,9 @@ func (client *ServiceClient) GetUserInfo(ctx context.Context, userInfo UserInfo,
 
 ## Overriding the Client Api Version Parameter
 
-By default, we find api version parameters in specs based off of names. There is special logic we do with api version parameters:
+By default, we find api version parameters in specs based off of names. Name-based detection applies to HTTP metadata parameters (header, query, path, or cookie) and server URL template parameters (declared in `@server`). A parameter named `apiVersion` or `api-version` in these positions will automatically be treated as an API version parameter.
+
+There is special logic we do with api version parameters:
 
 1. These api version parameters get elevated up to the client level (if the service is versioned)
 2. We auto-add api version information to next links when paging