@typespec/http 0.44.0-dev.4 → 0.44.0-dev.5

package/lib/auth.tsp

@@ -61,6 +61,7 @@ enum ApiKeyLocation {
 
 /**
  * An API key is a token that a client provides when making API calls. The key can be sent in the query string:
+ *
  * ```
  * GET /something?api_key=abcdef12345
  * ```
@@ -78,6 +79,9 @@ enum ApiKeyLocation {
  * GET /something HTTP/1.1
  * Cookie: X-API-KEY=abcdef12345
  * ```
+ *
+ * @template TLocation The location of the API key
+ * @template TName The name of the API key
  */
 model ApiKeyAuth<TLocation extends ApiKeyLocation, TName extends string> {
   @doc("API key authentication")
@@ -95,6 +99,7 @@ model ApiKeyAuth<TLocation extends ApiKeyLocation, TName extends string> {
  * OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials.
  * For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.
  * For more information about OAuth 2.0, see oauth.net and RFC 6749.
+ * @template TFlows The list of supported OAuth2 flows
  */
 model OAuth2Auth<TFlows extends OAuth2Flow[]> {
   @doc("OAuth2 authentication")

package/lib/http-decorators.tsp

@@ -202,6 +202,7 @@ extern dec useAuth(target: Namespace, auth: object | Union | object[]);
 
 /**
  * Specify if inapplicable metadata should be included in the payload for the given entity.
+ * @param value If true, inapplicable metadata will be included in the payload.
  */
 extern dec includeInapplicableMetadataInPayload(target: unknown, value: boolean);
 
@@ -215,7 +216,7 @@ extern dec includeInapplicableMetadataInPayload(target: unknown, value: boolean)
  * `@route` can only be applied to operations, namespaces, and interfaces.
  *
  * @param path Relative route path. Cannot include query parameters.
- * @param parameters Optional set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations.
+ * @param options Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations.
  *
  * @example
  *

package/lib/http.tsp

@@ -30,6 +30,9 @@ model Body<T> {
   body: T;
 }
 
+/**
+ * The Location header contains the URL where the status of the long running operation can be checked.
+ */
 model LocationHeader {
   @doc("The Location header contains the URL where the status of the long running operation can be checked.")
   @header
@@ -40,18 +43,52 @@ model LocationHeader {
 // to update the default descriptions for these status codes. This ensures
 // that we get consistent emit between different ways to spell the same
 // responses in TypeSpec.
+
+/**
+ * The request has succeeded.
+ */
 model OkResponse is Response<200>;
+/**
+ * The request has succeeded and a new resource has been created as a result.
+ */
 model CreatedResponse is Response<201>;
+/**
+ * The request has been accepted for processing, but processing has not yet completed.
+ */
 model AcceptedResponse is Response<202>;
+/**
+ * There is no content to send for this request, but the headers may be useful.
+ */
 model NoContentResponse is Response<204>;
+/**
+ * The URL of the requested resource has been changed permanently. The new URL is given in the response.
+ */
 model MovedResponse is Response<301> {
   ...LocationHeader;
 }
+/**
+ * The client has made a conditional request and the resource has not been modified.
+ */
 model NotModifiedResponse is Response<304>;
+/**
+ * The server could not understand the request due to invalid syntax.
+ */
 model BadRequestResponse is Response<400>;
+/**
+ * Access is unauthorized.
+ */
 model UnauthorizedResponse is Response<401>;
+/**
+ * Access is forbidden.
+ */
 model ForbiddenResponse is Response<403>;
+/**
+ * The server cannot find the requested resource.
+ */
 model NotFoundResponse is Response<404>;
+/**
+ * The request conflicts with the current state of the server.
+ */
 model ConflictResponse is Response<409>;
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typespec/http",
-  "version": "0.44.0-dev.4",
+  "version": "0.44.0-dev.5",
   "author": "Microsoft Corporation",
   "description": "TypeSpec HTTP protocol binding",
   "homepage": "https://github.com/Microsoft/typespec",