diff --git a/.chronus/changes/docs-http-2026-8-11.md b/.chronus/changes/docs-http-2026-8-11.md new file mode 100644 index 00000000000..9a153a9b9d5 --- /dev/null +++ b/.chronus/changes/docs-http-2026-8-11.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http" +--- + +Add missing documentation to public declarations and fix the `@route` `@param` name diff --git a/packages/http/README.md b/packages/http/README.md index 3600a1dfb10..f12885c3db5 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -296,6 +296,11 @@ op update(@header ifMatch: string): void; // headerName: if-match #### `@multipartBody` +Specify that the target property is the body of a multipart request or response. + +The property type must be a model or tuple whose members are all `HttpPart`, each describing one +part of the payload. + ```typespec @TypeSpec.Http.multipartBody ``` @@ -366,7 +371,7 @@ Explicitly specify that this property is to be interpolated as a path parameter. | Name | Type | Description | | ------------------ | --------------------------------------------- | -------------------------------------------------------------- | -| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the uri template or options. | +| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the URI template or options. | ##### Examples @@ -460,9 +465,9 @@ Defines the relative route URI template for the target operation as defined by [ ##### Parameters -| Name | Type | Description | -| ---- | ---------------- | ----------- | -| path | `valueof string` | | +| Name | Type | Description | +| ---- | ---------------- | -------------------------------- | +| path | `valueof string` | URI template for this operation. | ##### Examples diff --git a/packages/http/generated-defs/TypeSpec.Http.ts b/packages/http/generated-defs/TypeSpec.Http.ts index 9cf5c846e45..10543ac2732 100644 --- a/packages/http/generated-defs/TypeSpec.Http.ts +++ b/packages/http/generated-defs/TypeSpec.Http.ts @@ -134,7 +134,7 @@ export type QueryDecorator = ( /** * Explicitly specify that this property is to be interpolated as a path parameter. * - * @param paramNameOrOptions Optional name of the parameter in the uri template or options. + * @param paramNameOrOptions Optional name of the parameter in the URI template or options. * @example * ```typespec * @route("/read/{explicit}/things/{implicit}") @@ -178,17 +178,19 @@ export type BodyIgnoreDecorator = ( ) => DecoratorValidatorCallbacks | void; /** + * Specify that the target property is the body of a multipart request or response. * - * + * The property type must be a model or tuple whose members are all `HttpPart`, each describing one + * part of the payload. * * @example * ```tsp * op upload( * @header `content-type`: "multipart/form-data", * @multipartBody body: { - * fullName: HttpPart, - * headShots: HttpPart[] - * } + * fullName: HttpPart; + * headShots: HttpPart[]; + * }, * ): void; * ``` */ @@ -348,7 +350,7 @@ export type UseAuthDecorator = ( * * `@route` can only be applied to operations, namespaces, and interfaces. * - * @param uriTemplate Uri template for this operation. + * @param path URI template for this operation. * @example Simple path parameter * * ```typespec diff --git a/packages/http/lib/auth.tsp b/packages/http/lib/auth.tsp index 0b3920e1573..73d8936a765 100644 --- a/packages/http/lib/auth.tsp +++ b/packages/http/lib/auth.tsp @@ -232,5 +232,6 @@ model OpenIdConnectAuth */ @doc("") model NoAuth { + /** No authentication. */ type: AuthType.noAuth; } diff --git a/packages/http/lib/decorators.tsp b/packages/http/lib/decorators.tsp index 3082f405614..0e2203678e5 100644 --- a/packages/http/lib/decorators.tsp +++ b/packages/http/lib/decorators.tsp @@ -113,8 +113,11 @@ model QueryOptions { */ extern dec query(target: ModelProperty, queryNameOrOptions?: valueof string | QueryOptions); +/** + * Options for configuring how a path parameter is serialized into the URI template. + */ model PathOptions { - /** Name of the parameter in the uri template. */ + /** Name of the parameter in the URI template. */ name?: string; /** @@ -143,7 +146,7 @@ model PathOptions { /** * Explicitly specify that this property is to be interpolated as a path parameter. * - * @param paramNameOrOptions Optional name of the parameter in the uri template or options. + * @param paramNameOrOptions Optional name of the parameter in the URI template or options. * * @example * @@ -195,15 +198,20 @@ extern dec bodyRoot(target: ModelProperty); extern dec bodyIgnore(target: ModelProperty); /** + * Specify that the target property is the body of a multipart request or response. + * + * The property type must be a model or tuple whose members are all `HttpPart`, each describing one + * part of the payload. + * * @example * * ```tsp * op upload( * @header `content-type`: "multipart/form-data", * @multipartBody body: { - * fullName: HttpPart, - * headShots: HttpPart[] - * } + * fullName: HttpPart; + * headShots: HttpPart[]; + * }, * ): void; * ``` */ @@ -267,11 +275,11 @@ model PatchOptions { * If set to `false`, disables the implicit transform that makes the body of a * PATCH operation deeply optional. * - * @deprecated `implicitOptionality` is deprecated and will be removed. - * To preserve the previous behavior, define and use an explicit patch model - * with optional properties for your `@body` parameter. - * For actual JSON Merge Patch behavior, use `MergePatchUpdate` as the - * `@body` type (for example: `@patch op update(@body pet: MergePatchUpdate): void;`). + * **Deprecated:** `implicitOptionality` is deprecated and will be removed. + * To preserve the previous behavior, define and use an explicit patch model + * with optional properties for your `@body` parameter. + * For actual JSON Merge Patch behavior, use `MergePatchUpdate` as the + * `@body` type (for example: `@patch op update(@body pet: MergePatchUpdate): void;`). */ implicitOptionality?: boolean; } @@ -384,7 +392,7 @@ extern dec useAuth(target: Namespace | Interface | Operation, auth: {} | Union | * * `@route` can only be applied to operations, namespaces, and interfaces. * - * @param uriTemplate Uri template for this operation. + * @param path URI template for this operation. * * @example Simple path parameter * diff --git a/packages/http/lib/main.tsp b/packages/http/lib/main.tsp index 4ae9b68e1cd..908b78cea2b 100644 --- a/packages/http/lib/main.tsp +++ b/packages/http/lib/main.tsp @@ -256,20 +256,55 @@ model File; + * headShots: HttpPart[]; + * }, + * ): void; + * ``` + */ @Private.httpPart(Type, Options) model HttpPart {} +/** + * Describes a web link as defined by [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288). + */ model Link { + /** The target URI of the link. */ target: url; + + /** The relation type of the link, describing how the target relates to the current resource. */ rel: string; + + /** Additional target attributes to serialize as link parameters. */ attributes?: Record; } +/** + * A `Link` header value as defined by [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288). + * + * @template T The links carried by the header, either as a map of relation type to URI or as a + * list of `Link`. + */ scalar LinkHeader | Link[]> extends string; /** diff --git a/website/src/content/docs/docs/libraries/http/reference/data-types.md b/website/src/content/docs/docs/libraries/http/reference/data-types.md index 7375babe930..a72a2ce542d 100644 --- a/website/src/content/docs/docs/libraries/http/reference/data-types.md +++ b/website/src/content/docs/docs/libraries/http/reference/data-types.md @@ -370,16 +370,30 @@ model TypeSpec.Http.HeaderOptions ### `HttpPart` {#TypeSpec.Http.HttpPart} +Represents a single part of a multipart payload. + ```typespec model TypeSpec.Http.HttpPart ``` #### Template Parameters -| Name | Description | -| ------- | ----------- | -| Type | | -| Options | | +| Name | Description | +| ------- | ------------------------------------------------------------------------- | +| Type | The type of the part's content. | +| Options | Options for this part, such as the name to use when the part is repeated. | + +#### Examples + +```typespec +op upload( + @header `content-type`: "multipart/form-data", + @multipartBody body: { + fullName: HttpPart; + headShots: HttpPart[]; + }, +): void; +``` #### Properties @@ -387,6 +401,8 @@ None ### `HttpPartOptions` {#TypeSpec.Http.HttpPartOptions} +Options for configuring an individual part of a multipart payload. + ```typespec model TypeSpec.Http.HttpPartOptions ``` @@ -416,17 +432,19 @@ model TypeSpec.Http.ImplicitFlow ### `Link` {#TypeSpec.Http.Link} +Describes a web link as defined by [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288). + ```typespec model TypeSpec.Http.Link ``` #### Properties -| Name | Type | Description | -| ----------- | ----------------- | ----------- | -| target | `url` | | -| rel | `string` | | -| attributes? | `Record` | | +| Name | Type | Description | +| ----------- | ----------------- | ----------------------------------------------------------------------------------------- | +| target | `url` | The target URI of the link. | +| rel | `string` | The relation type of the link, describing how the target relates to the current resource. | +| attributes? | `Record` | Additional target attributes to serialize as link parameters. | ### `LocationHeader` {#TypeSpec.Http.LocationHeader} @@ -468,9 +486,9 @@ model TypeSpec.Http.NoAuth #### Properties -| Name | Type | Description | -| ---- | ------------------------------- | ----------- | -| type | `TypeSpec.Http.AuthType.noAuth` | | +| Name | Type | Description | +| ---- | ------------------------------- | ------------------ | +| type | `TypeSpec.Http.AuthType.noAuth` | No authentication. | ### `NoContentResponse` {#TypeSpec.Http.NoContentResponse} @@ -612,12 +630,14 @@ model TypeSpec.Http.PatchOptions #### Properties -| Name | Type | Description | -| -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- | -| implicitOptionality? | `boolean` | If set to `false`, disables the implicit transform that makes the body of a
PATCH operation deeply optional. | +| Name | Type | Description | +| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| implicitOptionality? | `boolean` | If set to `false`, disables the implicit transform that makes the body of a
PATCH operation deeply optional.

**Deprecated:** `implicitOptionality` is deprecated and will be removed.
To preserve the previous behavior, define and use an explicit patch model
with optional properties for your `@body` parameter.
For actual JSON Merge Patch behavior, use `MergePatchUpdate` as the
`@body` type (for example: `@patch op update(@body pet: MergePatchUpdate): void;`). | ### `PathOptions` {#TypeSpec.Http.PathOptions} +Options for configuring how a path parameter is serialized into the URI template. + ```typespec model TypeSpec.Http.PathOptions ``` @@ -626,7 +646,7 @@ model TypeSpec.Http.PathOptions | Name | Type | Description | | -------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| name? | `string` | Name of the parameter in the uri template. | +| name? | `string` | Name of the parameter in the URI template. | | explode? | `boolean` | When interpolating this parameter in the case of array or object expand each value using the given style.
Equivalent of adding `*` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) | | style? | `"simple" \| "label" \| "matrix" \| "fragment" \| "path"` | Different interpolating styles for the path parameter.
- `simple`: No special encoding.
- `label`: Using `.` separator.
- `matrix`: `;` as separator.
- `fragment`: `#` as separator.
- `path`: `/` as separator. | | allowReserved? | `boolean` | When interpolating this parameter do not encode reserved characters.
Equivalent of adding `+` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) | @@ -746,6 +766,8 @@ enum TypeSpec.Http.OAuth2FlowType ### `LinkHeader` {#TypeSpec.Http.LinkHeader} +A `Link` header value as defined by [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288). + ```typespec scalar TypeSpec.Http.LinkHeader ``` diff --git a/website/src/content/docs/docs/libraries/http/reference/decorators.md b/website/src/content/docs/docs/libraries/http/reference/decorators.md index 988fa1a6e50..4adfa6735e0 100644 --- a/website/src/content/docs/docs/libraries/http/reference/decorators.md +++ b/website/src/content/docs/docs/libraries/http/reference/decorators.md @@ -250,6 +250,11 @@ op update(@header ifMatch: string): void; // headerName: if-match ### `@multipartBody` {#@TypeSpec.Http.multipartBody} +Specify that the target property is the body of a multipart request or response. + +The property type must be a model or tuple whose members are all `HttpPart`, each describing one +part of the payload. + ```typespec @TypeSpec.Http.multipartBody ``` @@ -320,7 +325,7 @@ Explicitly specify that this property is to be interpolated as a path parameter. | Name | Type | Description | | ------------------ | --------------------------------------------- | -------------------------------------------------------------- | -| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the uri template or options. | +| paramNameOrOptions | `valueof string \| TypeSpec.Http.PathOptions` | Optional name of the parameter in the URI template or options. | #### Examples @@ -414,9 +419,9 @@ Defines the relative route URI template for the target operation as defined by [ #### Parameters -| Name | Type | Description | -| ---- | ---------------- | ----------- | -| path | `valueof string` | | +| Name | Type | Description | +| ---- | ---------------- | -------------------------------- | +| path | `valueof string` | URI template for this operation. | #### Examples