From c1ecc9d7422fc798471f53465885fd0616c5cadb Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Tue, 4 Aug 2026 15:44:41 -0400 Subject: [PATCH] docs(rest): remove bogus @template tags and document body parameters The operations inside the resource interface templates carried a copy of their enclosing interface's `@template` tags, documenting template parameters the operations do not have. Removes all 29 of them. Also escapes the `@path`/`@segment`/`@resource`/`@autoRoute` references in `rest-decorators.tsp`: without backticks (or a code fence, for the `@segment` example) the doc parser reads them as tags and silently drops the rest of the description. Prerequisite for microsoft/typespec#1229 and microsoft/typespec#2090. --- .chronus/changes/docs-rest-2026-8-11.md | 7 ++ packages/rest/README.md | 53 ++++++----- packages/rest/generated-defs/TypeSpec.Rest.ts | 51 +++------- packages/rest/lib/resource.tsp | 92 ++++++++----------- packages/rest/lib/rest-decorators.tsp | 21 +++-- .../libraries/rest/reference/data-types.md | 8 +- .../libraries/rest/reference/decorators.md | 53 ++++++----- 7 files changed, 134 insertions(+), 151 deletions(-) create mode 100644 .chronus/changes/docs-rest-2026-8-11.md diff --git a/.chronus/changes/docs-rest-2026-8-11.md b/.chronus/changes/docs-rest-2026-8-11.md new file mode 100644 index 00000000000..b007aba44ad --- /dev/null +++ b/.chronus/changes/docs-rest-2026-8-11.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/rest" +--- + +Remove doc comment `@template` tags that referenced the enclosing interface, and document the remaining operation body parameters diff --git a/packages/rest/README.md b/packages/rest/README.md index 2707bc94df8..17cb85def88 100644 --- a/packages/rest/README.md +++ b/packages/rest/README.md @@ -110,7 +110,7 @@ Specify this operation is a collection action. (Scopped to a resource, /pets/my- | Name | Type | Description | | ------------ | ---------------- | ----------------------------------------------------------------------------- | -| resourceType | `Model` | Resource marked with | +| resourceType | `Model` | Resource marked with `@resource` | | name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | #### `@copyResourceKeyParameters` @@ -145,9 +145,9 @@ Specify that this is a CreateOrReplace operation for a given resource. ##### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | #### `@createsOrUpdatesResource` @@ -163,9 +163,9 @@ Specify that this is a CreatesOrUpdate operation for a given resource. ##### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | #### `@createsResource` @@ -181,9 +181,9 @@ Specify that this is a Create operation for a given resource. ##### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | #### `@deletesResource` @@ -199,9 +199,9 @@ Specify that this is a Delete operation for a given resource. ##### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | #### `@listsResource` @@ -217,9 +217,9 @@ Specify that this is a List operation for a given resource. ##### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | #### `@parentResource` @@ -253,9 +253,9 @@ Specify that this is a Read operation for a given resource. ##### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | #### `@resource` @@ -277,7 +277,7 @@ Mark this model as a resource type with a name. #### `@segment` -Defines the preceding path segment for a +Defines the preceding path segment for a `@path` parameter in auto-generated routes. ```typespec @TypeSpec.Rest.segment(name: valueof string) @@ -295,6 +295,13 @@ Defines the preceding path segment for a ##### Examples +```typespec +@autoRoute +interface Pets { + get(@segment("pets") @path id: string): void; //-> route: /pets/{id} +} +``` + #### `@segmentOf` Returns the URL segment of a given model if it has `@segment` and `@key` decorator. @@ -327,6 +334,6 @@ Specify that this is a Update operation for a given resource. ##### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | diff --git a/packages/rest/generated-defs/TypeSpec.Rest.ts b/packages/rest/generated-defs/TypeSpec.Rest.ts index fd1a947b9b9..0a18ee19698 100644 --- a/packages/rest/generated-defs/TypeSpec.Rest.ts +++ b/packages/rest/generated-defs/TypeSpec.Rest.ts @@ -25,19 +25,16 @@ export type AutoRouteDecorator = ( ) => DecoratorValidatorCallbacks | void; /** - * Defines the preceding path segment for a + * Defines the preceding path segment for a `@path` parameter in auto-generated routes. * - * @path parameter in auto-generated routes. * @param name Segment that will be inserted into the operation route before the path parameter's name field. * @example - * - * + * ```typespec * @autoRoute * interface Pets { - * get( - * @segment ("pets") - * @path id: string): void; //-> route: /pets/{id} + * get(@segment("pets") @path id: string): void; //-> route: /pets/{id} * } + * ``` */ export type SegmentDecorator = ( context: DecoratorContext, @@ -96,10 +93,7 @@ export type ParentResourceDecorator = ( /** * Specify that this is a Read operation for a given resource. * - * @param resourceType Resource marked with - * @resource - * - * + * @param resourceType Resource marked with `@resource` */ export type ReadsResourceDecorator = ( context: DecoratorContext, @@ -110,10 +104,7 @@ export type ReadsResourceDecorator = ( /** * Specify that this is a Create operation for a given resource. * - * @param resourceType Resource marked with - * @resource - * - * + * @param resourceType Resource marked with `@resource` */ export type CreatesResourceDecorator = ( context: DecoratorContext, @@ -124,10 +115,7 @@ export type CreatesResourceDecorator = ( /** * Specify that this is a CreateOrReplace operation for a given resource. * - * @param resourceType Resource marked with - * @resource - * - * + * @param resourceType Resource marked with `@resource` */ export type CreatesOrReplacesResourceDecorator = ( context: DecoratorContext, @@ -138,10 +126,7 @@ export type CreatesOrReplacesResourceDecorator = ( /** * Specify that this is a CreatesOrUpdate operation for a given resource. * - * @param resourceType Resource marked with - * @resource - * - * + * @param resourceType Resource marked with `@resource` */ export type CreatesOrUpdatesResourceDecorator = ( context: DecoratorContext, @@ -152,10 +137,7 @@ export type CreatesOrUpdatesResourceDecorator = ( /** * Specify that this is a Update operation for a given resource. * - * @param resourceType Resource marked with - * @resource - * - * + * @param resourceType Resource marked with `@resource` */ export type UpdatesResourceDecorator = ( context: DecoratorContext, @@ -166,10 +148,7 @@ export type UpdatesResourceDecorator = ( /** * Specify that this is a Delete operation for a given resource. * - * @param resourceType Resource marked with - * @resource - * - * + * @param resourceType Resource marked with `@resource` */ export type DeletesResourceDecorator = ( context: DecoratorContext, @@ -180,10 +159,7 @@ export type DeletesResourceDecorator = ( /** * Specify that this is a List operation for a given resource. * - * @param resourceType Resource marked with - * @resource - * - * + * @param resourceType Resource marked with `@resource` */ export type ListsResourceDecorator = ( context: DecoratorContext, @@ -205,10 +181,7 @@ export type ActionDecorator = ( /** * Specify this operation is a collection action. (Scopped to a resource, /pets/my-action) * - * @param resourceType Resource marked with - * @resource - * - * + * @param resourceType Resource marked with `@resource` * @param name Name of the action. If not specified, the name of the operation will be used. */ export type CollectionActionDecorator = ( diff --git a/packages/rest/lib/resource.tsp b/packages/rest/lib/resource.tsp index c1d0ca9fbf2..e7f8332ac43 100644 --- a/packages/rest/lib/resource.tsp +++ b/packages/rest/lib/resource.tsp @@ -65,8 +65,6 @@ model ResourceCollectionParameters { interface ResourceRead { /** * Gets an instance of the resource. - * - * @template Resource The resource model. */ @autoRoute @doc("Gets an instance of the resource.") @@ -82,6 +80,8 @@ interface ResourceRead { @doc("Resource create operation completed successfully.") model ResourceCreatedResponse { ...CreatedResponse; + + /** The created resource. */ @bodyRoot body: Resource; } @@ -94,16 +94,17 @@ model ResourceCreatedResponse { interface ResourceCreateOrReplace { /** * Creates or replaces a instance of the resource. - * - * @template Resource The resource model to create or replace. - * @template Error The error response. */ @autoRoute @doc("Creates or replaces an instance of the resource.") @createsOrReplacesResource(Resource) createOrReplace( ...ResourceParameters, - @bodyRoot resource: ResourceCreateModel, + + /** The properties of the resource to create or replace. */ + @doc("") + @bodyRoot + resource: ResourceCreateModel, ): Resource | ResourceCreatedResponse | Error; } @@ -125,9 +126,6 @@ model ResourceCreateOrUpdateModel interface ResourceCreateOrUpdate { /** * Creates or update an instance of the resource. - * - * @template Resource The resource model to create or update. - * @template Error The error response. */ #suppress "@typespec/http/deprecated-implicit-optionality" "for legacy behavior" @autoRoute @@ -136,7 +134,11 @@ interface ResourceCreateOrUpdate { @patch(#{ implicitOptionality: true }) // for legacy behavior createOrUpdate( ...ResourceParameters, - @bodyRoot resource: ResourceCreateOrUpdateModel, + + /** The properties of the resource to create or update. */ + @doc("") + @bodyRoot + resource: ResourceCreateOrUpdateModel, ): Resource | ResourceCreatedResponse | Error; } @@ -158,16 +160,17 @@ model ResourceCreateModel is DefaultKeyVisibility { /** * Creates a new instance of the resource. - * - * @template Resource The resource model to create. - * @template Error The error response. */ @autoRoute @doc("Creates a new instance of the resource.") @createsResource(Resource) create( ...ResourceCollectionParameters, - @bodyRoot resource: ResourceCreateModel, + + /** The properties of the resource to create. */ + @doc("") + @bodyRoot + resource: ResourceCreateModel, ): Resource | ResourceCreatedResponse | Error; } @@ -182,9 +185,6 @@ interface ResourceCreate { interface ResourceUpdate { /** * Updates an existing instance of the resource. - * - * @template Resource The resource model to update. - * @template Error The error response. */ #suppress "@typespec/http/deprecated-implicit-optionality" "for legacy behavior" @autoRoute @@ -193,7 +193,11 @@ interface ResourceUpdate { @patch(#{ implicitOptionality: true }) // for legacy behavior update( ...ResourceParameters, - @bodyRoot properties: ResourceCreateOrUpdateModel, + + /** The properties of the resource to update. */ + @doc("") + @bodyRoot + properties: ResourceCreateOrUpdateModel, ): Resource | Error; } @@ -215,9 +219,6 @@ model ResourceDeletedResponse { interface ResourceDelete { /** * Deletes an existing instance of the resource. - * - * @template Resource The resource model to delete. - * @template Error The error response. */ @autoRoute @doc("Deletes an existing instance of the resource.") @@ -251,9 +252,6 @@ model CollectionWithNextLink { interface ResourceList { /** * Lists all instances of the resource. - * - * @template Resource The resource model to list. - * @template Error The error response. */ @autoRoute @doc("Lists all instances of the resource.") @@ -310,9 +308,6 @@ interface ResourceOperations interface SingletonResourceRead { /** * Gets the singleton resource. - * - * @template Singleton The singleton resource model. - * @template Resource The resource model. */ @autoRoute @doc("Gets the singleton resource.") @@ -333,9 +328,6 @@ interface SingletonResourceRead { /** * Updates the singleton resource. - * - * @template Singleton The singleton resource model. - * @template Resource The resource model. */ #suppress "@typespec/http/deprecated-implicit-optionality" "for legacy behavior" @autoRoute @@ -346,6 +338,8 @@ interface SingletonResourceUpdate, + /** The properties of the singleton resource to update. */ + @doc("") @body properties: ResourceCreateOrUpdateModel, ): Singleton | Error; @@ -374,9 +368,6 @@ interface SingletonResourceOperations { /** * Gets an instance of the extension resource. - * - * @template Extension The extension resource model. - * @template Resource The resource model. */ @autoRoute @doc("Gets an instance of the extension resource.") @@ -394,9 +385,6 @@ interface ExtensionResourceRead { /** * Creates or update an instance of the extension resource. - * - * @template Extension The extension resource model. - * @template Resource The resource model. */ #suppress "@typespec/http/deprecated-implicit-optionality" "for legacy behavior" @autoRoute @@ -406,7 +394,11 @@ interface ExtensionResourceCreateOrUpdate, ...ResourceParameters, - @bodyRoot resource: ResourceCreateOrUpdateModel, + + /** The properties of the extension resource to create or update. */ + @doc("") + @bodyRoot + resource: ResourceCreateOrUpdateModel, ): Extension | ResourceCreatedResponse | Error; } @@ -420,17 +412,18 @@ interface ExtensionResourceCreateOrUpdate { /** * Creates a new instance of the extension resource. - * - * @template Extension The extension resource model. - * @template Resource The resource model. */ @autoRoute @doc("Creates a new instance of the extension resource.") @createsResource(Extension) - create(...ResourceParameters, @bodyRoot resource: ResourceCreateModel): - | Extension - | ResourceCreatedResponse - | Error; + create( + ...ResourceParameters, + + /** The properties of the extension resource to create. */ + @doc("") + @bodyRoot + resource: ResourceCreateModel, + ): Extension | ResourceCreatedResponse | Error; } /** @@ -443,9 +436,6 @@ interface ExtensionResourceCreate { /** * Updates an existing instance of the extension resource. - * - * @template Extension The extension resource model. - * @template Resource The resource model. */ #suppress "@typespec/http/deprecated-implicit-optionality" "for legacy behavior" @autoRoute @@ -456,6 +446,8 @@ interface ExtensionResourceUpdate, ...ResourceParameters, + /** The properties of the extension resource to update. */ + @doc("") @body properties: ResourceCreateOrUpdateModel, ): Extension | Error; @@ -471,9 +463,6 @@ interface ExtensionResourceUpdate { /** * Deletes an existing instance of the extension resource. - * - * @template Extension The extension resource model. - * @template Resource The resource model. */ @autoRoute @doc("Deletes an existing instance of the extension resource.") @@ -493,9 +482,6 @@ interface ExtensionResourceDelete { /** * Lists all instances of the extension resource. - * - * @template Extension The extension resource model. - * @template Resource The resource model. */ @autoRoute @doc("Lists all instances of the extension resource.") diff --git a/packages/rest/lib/rest-decorators.tsp b/packages/rest/lib/rest-decorators.tsp index c430c13c6cd..e62663ad601 100644 --- a/packages/rest/lib/rest-decorators.tsp +++ b/packages/rest/lib/rest-decorators.tsp @@ -17,15 +17,18 @@ using TypeSpec.Reflection; extern dec autoRoute(target: Interface | Operation); /** - * Defines the preceding path segment for a @path parameter in auto-generated routes. + * Defines the preceding path segment for a `@path` parameter in auto-generated routes. * * @param name Segment that will be inserted into the operation route before the path parameter's name field. * * @example + * + * ```typespec * @autoRoute * interface Pets { * get(@segment("pets") @path id: string): void; //-> route: /pets/{id} * } + * ``` */ extern dec segment(target: Model | ModelProperty | Operation, name: valueof string); @@ -65,49 +68,49 @@ extern dec parentResource(target: Model, parent: Model); /** * Specify that this is a Read operation for a given resource. * - * @param resourceType Resource marked with @resource + * @param resourceType Resource marked with `@resource` */ extern dec readsResource(target: Operation, resourceType: Model); /** * Specify that this is a Create operation for a given resource. * - * @param resourceType Resource marked with @resource + * @param resourceType Resource marked with `@resource` */ extern dec createsResource(target: Operation, resourceType: Model); /** * Specify that this is a CreateOrReplace operation for a given resource. * - * @param resourceType Resource marked with @resource + * @param resourceType Resource marked with `@resource` */ extern dec createsOrReplacesResource(target: Operation, resourceType: Model); /** * Specify that this is a CreatesOrUpdate operation for a given resource. * - * @param resourceType Resource marked with @resource + * @param resourceType Resource marked with `@resource` */ extern dec createsOrUpdatesResource(target: Operation, resourceType: Model); /** * Specify that this is a Update operation for a given resource. * - * @param resourceType Resource marked with @resource + * @param resourceType Resource marked with `@resource` */ extern dec updatesResource(target: Operation, resourceType: Model); /** * Specify that this is a Delete operation for a given resource. * - * @param resourceType Resource marked with @resource + * @param resourceType Resource marked with `@resource` */ extern dec deletesResource(target: Operation, resourceType: Model); /** * Specify that this is a List operation for a given resource. * - * @param resourceType Resource marked with @resource + * @param resourceType Resource marked with `@resource` */ extern dec listsResource(target: Operation, resourceType: Model); @@ -119,7 +122,7 @@ extern dec action(target: Operation, name?: valueof string); /** * Specify this operation is a collection action. (Scopped to a resource, /pets/my-action) - * @param resourceType Resource marked with @resource + * @param resourceType Resource marked with `@resource` * @param name Name of the action. If not specified, the name of the operation will be used. */ extern dec collectionAction(target: Operation, resourceType: Model, name?: valueof string); diff --git a/website/src/content/docs/docs/libraries/rest/reference/data-types.md b/website/src/content/docs/docs/libraries/rest/reference/data-types.md index df25532bb14..c6b8e216f16 100644 --- a/website/src/content/docs/docs/libraries/rest/reference/data-types.md +++ b/website/src/content/docs/docs/libraries/rest/reference/data-types.md @@ -107,10 +107,10 @@ model TypeSpec.Rest.Resource.ResourceCreatedResponse #### Properties -| Name | Type | Description | -| ---------- | ---------- | ---------------- | -| statusCode | `201` | The status code. | -| body | `Resource` | | +| Name | Type | Description | +| ---------- | ---------- | --------------------- | +| statusCode | `201` | The status code. | +| body | `Resource` | The created resource. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} diff --git a/website/src/content/docs/docs/libraries/rest/reference/decorators.md b/website/src/content/docs/docs/libraries/rest/reference/decorators.md index da4c3f85567..56e2187fba0 100644 --- a/website/src/content/docs/docs/libraries/rest/reference/decorators.md +++ b/website/src/content/docs/docs/libraries/rest/reference/decorators.md @@ -89,7 +89,7 @@ Specify this operation is a collection action. (Scopped to a resource, /pets/my- | Name | Type | Description | | ------------ | ---------------- | ----------------------------------------------------------------------------- | -| resourceType | `Model` | Resource marked with | +| resourceType | `Model` | Resource marked with `@resource` | | name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | ### `@copyResourceKeyParameters` {#@TypeSpec.Rest.copyResourceKeyParameters} @@ -124,9 +124,9 @@ Specify that this is a CreateOrReplace operation for a given resource. #### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | ### `@createsOrUpdatesResource` {#@TypeSpec.Rest.createsOrUpdatesResource} @@ -142,9 +142,9 @@ Specify that this is a CreatesOrUpdate operation for a given resource. #### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | ### `@createsResource` {#@TypeSpec.Rest.createsResource} @@ -160,9 +160,9 @@ Specify that this is a Create operation for a given resource. #### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | ### `@deletesResource` {#@TypeSpec.Rest.deletesResource} @@ -178,9 +178,9 @@ Specify that this is a Delete operation for a given resource. #### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | ### `@listsResource` {#@TypeSpec.Rest.listsResource} @@ -196,9 +196,9 @@ Specify that this is a List operation for a given resource. #### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | ### `@parentResource` {#@TypeSpec.Rest.parentResource} @@ -232,9 +232,9 @@ Specify that this is a Read operation for a given resource. #### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` | ### `@resource` {#@TypeSpec.Rest.resource} @@ -256,7 +256,7 @@ Mark this model as a resource type with a name. ### `@segment` {#@TypeSpec.Rest.segment} -Defines the preceding path segment for a +Defines the preceding path segment for a `@path` parameter in auto-generated routes. ```typespec @TypeSpec.Rest.segment(name: valueof string) @@ -274,6 +274,13 @@ Defines the preceding path segment for a #### Examples +```typespec +@autoRoute +interface Pets { + get(@segment("pets") @path id: string): void; //-> route: /pets/{id} +} +``` + ### `@segmentOf` {#@TypeSpec.Rest.segmentOf} Returns the URL segment of a given model if it has `@segment` and `@key` decorator. @@ -306,6 +313,6 @@ Specify that this is a Update operation for a given resource. #### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------- | -| resourceType | `Model` | Resource marked with | +| Name | Type | Description | +| ------------ | ------- | -------------------------------- | +| resourceType | `Model` | Resource marked with `@resource` |