fix api reports for openapi-utils

Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>
Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

packages/backend-openapi-utils/report.api.md

@@ -102,12 +102,45 @@ export function createValidatedOpenApiRouter<T extends RequiredDoc>(
   },
 ): ApiRouter<T>;
 
+// @public
+export function createValidatedOpenApiRouterFromGeneratedEndpointMap<
+  T extends EndpointMap,
+>(
+  spec: RequiredDoc,
+  options?: {
+    validatorOptions?: Partial<Parameters<typeof middleware>['0']>;
+    middleware?: RequestHandler[];
+  },
+): TypedRouter<T>;
+
 // @public (undocumented)
 type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
   T,
   Record<K, V>
 >;
 
+// @public (undocumented)
+type DocEndpoint<Doc extends EndpointMap> = ValueOf<{
+  [Template in keyof Doc]: Template extends `#${string}|${infer Endpoint}`
+    ? Endpoint
+    : never;
+}>;
+
+// @public (undocumented)
+type DocEndpointMethod<
+  Doc extends EndpointMap,
+  Endpoint extends DocEndpoint<Doc>,
+> = ValueOf<{
+  [Template in keyof Doc]: Template extends `#${infer Method}|${Endpoint}`
+    ? Method
+    : never;
+}>;
+
+// @public (undocumented)
+type DocEndpointTemplate<Doc extends EndpointMap> = PathTemplate<
+  DocEndpoint<Doc>
+>;
+
 // @public (undocumented)
 type DocOperation<
   Doc extends RequiredDoc,
@@ -239,6 +272,85 @@ interface DocRequestMatcher<
   ): T;
 }
 
+// @public (undocumented)
+type EndpointMap = Record<
+  string,
+  {
+    query?: object;
+    body?: object;
+    response?: object;
+    path?: object;
+  }
+>;
+
+// @public
+type EndpointMapRequestHandler<
+  Doc extends EndpointMap,
+  Path extends DocEndpoint<Doc>,
+  Method extends DocEndpointMethod<Doc, Path>,
+> = core.RequestHandler<
+  StaticPathParamsSchema<Doc, Path, Method>,
+  StaticResponseSchema<Doc, Path, Method>,
+  StaticRequestBodySchema<Doc, Path, Method>,
+  StaticQueryParamsSchema<Doc, Path, Method>,
+  Record<string, string>
+>;
+
+// @public
+type EndpointMapRequestHandlerParams<
+  Doc extends EndpointMap,
+  Path extends DocEndpoint<Doc>,
+  Method extends DocEndpointMethod<Doc, Path>,
+> = core.RequestHandlerParams<
+  StaticPathParamsSchema<Doc, Path, Method>,
+  StaticResponseSchema<Doc, Path, Method>,
+  StaticRequestBodySchema<Doc, Path, Method>,
+  StaticQueryParamsSchema<Doc, Path, Method>,
+  Record<string, string>
+>;
+
+// @public
+interface EndpointMapRequestMatcher<
+  Doc extends EndpointMap,
+  T,
+  Method extends HttpMethods,
+> {
+  // (undocumented)
+  <
+    TPath extends MethodAwareDocEndpoints<
+      Doc,
+      DocEndpoint<Doc>,
+      Method & DocEndpointMethod<Doc, DocEndpoint<Doc>>
+    >,
+    TMethod extends Method &
+      DocEndpointMethod<Doc, TemplateToDocEndpoint<Doc, TPath>>,
+  >(
+    path: TPath,
+    ...handlers: Array<
+      EndpointMapRequestHandler<Doc, TemplateToDocEndpoint<Doc, TPath>, TMethod>
+    >
+  ): T;
+  // (undocumented)
+  <
+    TPath extends MethodAwareDocEndpoints<
+      Doc,
+      DocEndpoint<Doc>,
+      Method & DocEndpointMethod<Doc, DocEndpoint<Doc>>
+    >,
+    TMethod extends Method &
+      DocEndpointMethod<Doc, TemplateToDocEndpoint<Doc, TPath>>,
+  >(
+    path: TPath,
+    ...handlers: Array<
+      EndpointMapRequestHandlerParams<
+        Doc,
+        TemplateToDocEndpoint<Doc, TPath>,
+        TMethod
+      >
+    >
+  ): T;
+}
+
 // @public (undocumented)
 type Filter<T, U> = T extends U ? T : never;
 
@@ -278,6 +390,9 @@ type HeaderSchema<
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, Path, Method, ImmutableHeaderObject>;
 
+// @public (undocumented)
+type HttpMethods = 'all' | 'put' | 'get' | 'post' | '_delete';
+
 // @public
 type Immutable<T> = T extends
   | Function
@@ -401,6 +516,21 @@ declare namespace internal {
     Response_3 as Response,
     ResponseSchemas,
     ResponseBodyToJsonSchema,
+    EndpointMap,
+    HttpMethods,
+    StaticPathParamsSchema,
+    StaticRequestBodySchema,
+    StaticResponseSchema,
+    StaticQueryParamsSchema,
+    EndpointMapRequestHandler,
+    EndpointMapRequestHandlerParams,
+    DocEndpoint,
+    DocEndpointMethod,
+    MethodAwareDocEndpoints,
+    DocEndpointTemplate,
+    TemplateToDocEndpoint,
+    EndpointMapRequestMatcher,
+    TypedRouter,
   };
 }
 export { internal };
@@ -427,6 +557,19 @@ type MapToSchema<
     : never;
 };
 
+// @public (undocumented)
+type MethodAwareDocEndpoints<
+  Doc extends EndpointMap,
+  Endpoint extends DocEndpoint<Doc>,
+  Method extends DocEndpointMethod<Doc, Endpoint>,
+> = ValueOf<{
+  [Template in keyof Doc]: Template extends `#${Method}|${infer E}`
+    ? E extends DocEndpoint<Doc>
+      ? PathTemplate<E>
+      : never
+    : never;
+}>;
+
 // @public (undocumented)
 type MethodAwareDocPath<
   Doc extends PathDoc,
@@ -513,7 +656,7 @@ type PathSchema<
 > = ParametersSchema<Doc, Path, Method, ImmutablePathObject>;
 
 // @public
-type PathTemplate<Path extends string> =
+export type PathTemplate<Path extends string> =
   Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}`
     ? `${Prefix}:${PathName}${PathTemplate<Suffix>}`
     : Path;
@@ -684,6 +827,60 @@ type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
       [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]>;
     };
 
+// @public (undocumented)
+type StaticPathParamsSchema<
+  Doc extends EndpointMap,
+  Endpoint extends DocEndpoint<Doc>,
+  Method extends DocEndpointMethod<Doc, Endpoint>,
+> = `#${Method}|${Endpoint}` extends keyof Doc
+  ? 'path' extends keyof Doc[`#${Method}|${Endpoint}`]
+    ? Doc[`#${Method}|${Endpoint}`]['path']
+    : never
+  : never;
+
+// @public (undocumented)
+type StaticQueryParamsSchema<
+  Doc extends EndpointMap,
+  Endpoint extends DocEndpoint<Doc>,
+  Method extends DocEndpointMethod<Doc, Endpoint>,
+> = `#${Method}|${Endpoint}` extends keyof Doc
+  ? 'query' extends keyof Doc[`#${Method}|${Endpoint}`]
+    ? Doc[`#${Method}|${Endpoint}`]['query']
+    : never
+  : never;
+
+// @public (undocumented)
+type StaticRequestBodySchema<
+  Doc extends EndpointMap,
+  Endpoint extends DocEndpoint<Doc>,
+  Method extends DocEndpointMethod<Doc, Endpoint>,
+> = `#${Method}|${Endpoint}` extends keyof Doc
+  ? 'body' extends keyof Doc[`#${Method}|${Endpoint}`]
+    ? Doc[`#${Method}|${Endpoint}`]['body']
+    : unknown
+  : unknown;
+
+// @public (undocumented)
+type StaticResponseSchema<
+  Doc extends EndpointMap,
+  Endpoint extends DocEndpoint<Doc>,
+  Method extends DocEndpointMethod<Doc, Endpoint>,
+> = `#${Method}|${Endpoint}` extends keyof Doc
+  ? 'response' extends keyof Doc[`#${Method}|${Endpoint}`]
+    ? Doc[`#${Method}|${Endpoint}`]['response']
+    : unknown
+  : unknown;
+
+// @public (undocumented)
+type TemplateToDocEndpoint<
+  Doc extends EndpointMap,
+  Path extends DocEndpointTemplate<Doc>,
+> = ValueOf<{
+  [Template in DocEndpoint<Doc>]: Path extends PathTemplate<Template>
+    ? Template
+    : never;
+}>;
+
 // @public
 type TemplateToDocPath<
   Doc extends PathDoc,
@@ -704,6 +901,18 @@ type TuplifyUnion<
   N = [T] extends [never] ? true : false,
 > = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
 
+// @public (undocumented)
+interface TypedRouter<GeneratedEndpointMap extends EndpointMap> extends Router {
+  // (undocumented)
+  delete: EndpointMapRequestMatcher<GeneratedEndpointMap, this, '_delete'>;
+  // (undocumented)
+  get: EndpointMapRequestMatcher<GeneratedEndpointMap, this, 'get'>;
+  // (undocumented)
+  post: EndpointMapRequestMatcher<GeneratedEndpointMap, this, 'post'>;
+  // (undocumented)
+  put: EndpointMapRequestMatcher<GeneratedEndpointMap, this, 'put'>;
+}
+
 // @public
 type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
   k: infer I,

packages/backend-openapi-utils/src/index.ts

@@ -31,10 +31,6 @@ export type {
   PathParameters,
 } from './utility';
 export type { ApiRouter } from './router';
-export type {
-  RequestMatcherByModelAndPath,
-  RequestMatcherByModelAndPathParams,
-} from './types/express';
 export type { PathTemplate } from './types/common';
 export { wrapInOpenApiTestServer, wrapServer } from './testUtils';
 export {

packages/backend-openapi-utils/src/types/express.ts

@@ -100,29 +100,3 @@ export interface DocRequestMatcher<
     >
   ): T;
 }
-
-export type RequestMatcherByModelAndPath<
-  PathParams,
-  QueryParams,
-  RequestBody,
-  ResponseBody,
-> = core.RequestHandler<
-  PathParams,
-  ResponseBody,
-  RequestBody,
-  QueryParams,
-  Record<string, string>
->;
-
-export type RequestMatcherByModelAndPathParams<
-  PathParams,
-  QueryParams,
-  RequestBody,
-  ResponseBody,
-> = core.RequestHandlerParams<
-  PathParams,
-  ResponseBody,
-  RequestBody,
-  QueryParams,
-  Record<string, string>
->;

packages/backend-openapi-utils/src/types/generated.ts

@@ -17,15 +17,24 @@ import { Router } from 'express';
 import type core from 'express-serve-static-core';
 import { PathTemplate, ValueOf } from './common';
 
+/**
+ * @public
+ */
 export type EndpointMap = Record<
   string,
   { query?: object; body?: object; response?: object; path?: object }
 >;
 
 // OpenAPI generator doesn't emit regular lowercase 'delete'.
-type HttpMethods = 'all' | 'put' | 'get' | 'post' | '_delete';
+/**
+ * @public
+ */
+export type HttpMethods = 'all' | 'put' | 'get' | 'post' | '_delete';
 
-type PathSchema<
+/**
+ * @public
+ */
+export type StaticPathParamsSchema<
   Doc extends EndpointMap,
   Endpoint extends DocEndpoint<Doc>,
   Method extends DocEndpointMethod<Doc, Endpoint>,
@@ -34,7 +43,10 @@ type PathSchema<
     ? Doc[`#${Method}|${Endpoint}`]['path']
     : never
   : never;
-type RequestBody<
+/**
+ * @public
+ */
+export type StaticRequestBodySchema<
   Doc extends EndpointMap,
   Endpoint extends DocEndpoint<Doc>,
   Method extends DocEndpointMethod<Doc, Endpoint>,
@@ -43,7 +55,10 @@ type RequestBody<
     ? Doc[`#${Method}|${Endpoint}`]['body']
     : unknown
   : unknown;
-type ResponseBody<
+/**
+ * @public
+ */
+export type StaticResponseSchema<
   Doc extends EndpointMap,
   Endpoint extends DocEndpoint<Doc>,
   Method extends DocEndpointMethod<Doc, Endpoint>,
@@ -52,7 +67,10 @@ type ResponseBody<
     ? Doc[`#${Method}|${Endpoint}`]['response']
     : unknown
   : unknown;
-type QuerySchema<
+/**
+ * @public
+ */
+export type StaticQueryParamsSchema<
   Doc extends EndpointMap,
   Endpoint extends DocEndpoint<Doc>,
   Method extends DocEndpointMethod<Doc, Endpoint>,
@@ -71,10 +89,10 @@ export type EndpointMapRequestHandler<
   Path extends DocEndpoint<Doc>,
   Method extends DocEndpointMethod<Doc, Path>,
 > = core.RequestHandler<
-  PathSchema<Doc, Path, Method>,
-  ResponseBody<Doc, Path, Method>,
-  RequestBody<Doc, Path, Method>,
-  QuerySchema<Doc, Path, Method>,
+  StaticPathParamsSchema<Doc, Path, Method>,
+  StaticResponseSchema<Doc, Path, Method>,
+  StaticRequestBodySchema<Doc, Path, Method>,
+  StaticQueryParamsSchema<Doc, Path, Method>,
   Record<string, string>
 >;
 
@@ -87,20 +105,26 @@ export type EndpointMapRequestHandlerParams<
   Path extends DocEndpoint<Doc>,
   Method extends DocEndpointMethod<Doc, Path>,
 > = core.RequestHandlerParams<
-  PathSchema<Doc, Path, Method>,
-  ResponseBody<Doc, Path, Method>,
-  RequestBody<Doc, Path, Method>,
-  QuerySchema<Doc, Path, Method>,
+  StaticPathParamsSchema<Doc, Path, Method>,
+  StaticResponseSchema<Doc, Path, Method>,
+  StaticRequestBodySchema<Doc, Path, Method>,
+  StaticQueryParamsSchema<Doc, Path, Method>,
   Record<string, string>
 >;
 
-type DocEndpoint<Doc extends EndpointMap> = ValueOf<{
+/**
+ * @public
+ */
+export type DocEndpoint<Doc extends EndpointMap> = ValueOf<{
   [Template in keyof Doc]: Template extends `#${string}|${infer Endpoint}`
     ? Endpoint
     : never;
 }>;
 
-type DocEndpointMethod<
+/**
+ * @public
+ */
+export type DocEndpointMethod<
   Doc extends EndpointMap,
   Endpoint extends DocEndpoint<Doc>,
 > = ValueOf<{
@@ -109,7 +133,10 @@ type DocEndpointMethod<
     : never;
 }>;
 
-type MethodAwareDocEndpoints<
+/**
+ * @public
+ */
+export type MethodAwareDocEndpoints<
   Doc extends EndpointMap,
   Endpoint extends DocEndpoint<Doc>,
   Method extends DocEndpointMethod<Doc, Endpoint>,
@@ -121,10 +148,16 @@ type MethodAwareDocEndpoints<
     : never;
 }>;
 
-type DocEndpointTemplate<Doc extends EndpointMap> = PathTemplate<
+/**
+ * @public
+ */
+export type DocEndpointTemplate<Doc extends EndpointMap> = PathTemplate<
   DocEndpoint<Doc>
 >;
 
+/**
+ * @public
+ */
 export type TemplateToDocEndpoint<
   Doc extends EndpointMap,
   Path extends DocEndpointTemplate<Doc>,
@@ -177,6 +210,9 @@ export interface EndpointMapRequestMatcher<
   ): T;
 }
 
+/**
+ * @public
+ */
 export interface TypedRouter<GeneratedEndpointMap extends EndpointMap>
   extends Router {
   get: EndpointMapRequestMatcher<GeneratedEndpointMap, this, 'get'>;

packages/catalog-client/api-report-alpha.md

@@ -83,8 +83,6 @@ export interface CreateLocationRequest {
   type: string;
 }
 
-// Warning: (ae-missing-release-tag) "DefaultApiClient" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class DefaultApiClient {
   constructor(options: {
@@ -95,87 +93,54 @@ export class DefaultApiClient {
       fetch: typeof fetch;
     };
   });
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   analyzeLocation(
     request: AnalyzeLocation,
     options?: RequestOptions,
   ): Promise<TypedResponse<AnalyzeLocationResponse>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   createLocation(
     request: CreateLocation,
     options?: RequestOptions,
   ): Promise<TypedResponse<CreateLocation201Response>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   deleteEntityByUid(
     request: DeleteEntityByUid,
     options?: RequestOptions,
   ): Promise<TypedResponse<void>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   deleteLocation(
     request: DeleteLocation,
     options?: RequestOptions,
   ): Promise<TypedResponse<void>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   getEntities(
     request: GetEntities,
     options?: RequestOptions,
   ): Promise<TypedResponse<Array<Entity>>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   getEntitiesByQuery(
     request: GetEntitiesByQuery,
     options?: RequestOptions,
   ): Promise<TypedResponse<EntitiesQueryResponse>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   getEntitiesByRefs(
     request: GetEntitiesByRefs,
     options?: RequestOptions,
   ): Promise<TypedResponse<EntitiesBatchResponse>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   getEntityAncestryByName(
     request: GetEntityAncestryByName,
     options?: RequestOptions,
   ): Promise<TypedResponse<EntityAncestryResponse>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   getEntityByName(
     request: GetEntityByName,
     options?: RequestOptions,
   ): Promise<TypedResponse<Entity>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   getEntityByUid(
     request: GetEntityByUid,
     options?: RequestOptions,
   ): Promise<TypedResponse<Entity>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   getEntityFacets(
     request: GetEntityFacets,
     options?: RequestOptions,
   ): Promise<TypedResponse<EntityFacetsResponse>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   getLocation(
     request: GetLocation,
     options?: RequestOptions,
   ): Promise<TypedResponse<Location_2>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   getLocationByEntity(
     request: GetLocationByEntity,
     options?: RequestOptions,
@@ -184,12 +149,10 @@ export class DefaultApiClient {
     request: GetLocations,
     options?: RequestOptions,
   ): Promise<TypedResponse<Array<GetLocations200ResponseInner>>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   refreshEntity(
     request: RefreshEntity,
     options?: RequestOptions,
   ): Promise<TypedResponse<void>>;
-  // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   validateEntity(
     request: ValidateEntity,
     options?: RequestOptions,

packages/catalog-client/src/generated/apis/DefaultApi.client.ts

@@ -197,6 +197,7 @@ export type ValidateEntity = {
 
 /**
  * no description
+ * @public
  */
 export class DefaultApiClient {
   private readonly discoveryApi: DiscoveryApi;
@@ -212,7 +213,7 @@ export class DefaultApiClient {
 
   /**
    * Validate a given location.
-   * @param analyzeLocationRequest
+   * @param analyzeLocationRequest -
    */
   public async analyzeLocation(
     // @ts-ignore
@@ -237,8 +238,8 @@ export class DefaultApiClient {
 
   /**
    * Create a location for a given target.
-   * @param createLocationRequest
-   * @param dryRun
+   * @param createLocationRequest -
+   * @param dryRun -
    */
   public async createLocation(
     // @ts-ignore
@@ -265,7 +266,7 @@ export class DefaultApiClient {
 
   /**
    * Delete a single entity by UID.
-   * @param uid
+   * @param uid -
    */
   public async deleteEntityByUid(
     // @ts-ignore
@@ -291,7 +292,7 @@ export class DefaultApiClient {
 
   /**
    * Delete a location by id.
-   * @param id
+   * @param id -
    */
   public async deleteLocation(
     // @ts-ignore
@@ -317,12 +318,12 @@ export class DefaultApiClient {
 
   /**
    * Get all entities matching a given filter.
-   * @param fields Restrict to just these fields in the response.
-   * @param limit Number of records to return in the response.
-   * @param filter Filter for just the entities defined by this filter.
-   * @param offset Number of records to skip in the query page.
-   * @param after Pointer to the previous page of results.
-   * @param order
+   * @param fields - Restrict to just these fields in the response.
+   * @param limit - Number of records to return in the response.
+   * @param filter - Filter for just the entities defined by this filter.
+   * @param offset - Number of records to skip in the query page.
+   * @param after - Pointer to the previous page of results.
+   * @param order -
    */
   public async getEntities(
     // @ts-ignore
@@ -348,13 +349,13 @@ export class DefaultApiClient {
 
   /**
    * Search for entities by a given query.
-   * @param fields Restrict to just these fields in the response.
-   * @param limit Number of records to return in the response.
-   * @param orderField The fields to sort returned results by.
-   * @param cursor Cursor to a set page of results.
-   * @param filter Filter for just the entities defined by this filter.
-   * @param fullTextFilterTerm Text search term.
-   * @param fullTextFilterFields A comma separated list of fields to sort returned results by.
+   * @param fields - Restrict to just these fields in the response.
+   * @param limit - Number of records to return in the response.
+   * @param orderField - The fields to sort returned results by.
+   * @param cursor - Cursor to a set page of results.
+   * @param filter - Filter for just the entities defined by this filter.
+   * @param fullTextFilterTerm - Text search term.
+   * @param fullTextFilterFields - A comma separated list of fields to sort returned results by.
    */
   public async getEntitiesByQuery(
     // @ts-ignore
@@ -380,8 +381,8 @@ export class DefaultApiClient {
 
   /**
    * Get a batch set of entities given an array of entityRefs.
-   * @param filter Filter for just the entities defined by this filter.
-   * @param getEntitiesByRefsRequest
+   * @param filter - Filter for just the entities defined by this filter.
+   * @param getEntitiesByRefsRequest -
    */
   public async getEntitiesByRefs(
     // @ts-ignore
@@ -408,9 +409,9 @@ export class DefaultApiClient {
 
   /**
    * Get an entity's ancestry by entity ref.
-   * @param kind
-   * @param namespace
-   * @param name
+   * @param kind -
+   * @param namespace -
+   * @param name -
    */
   public async getEntityAncestryByName(
     // @ts-ignore
@@ -438,9 +439,9 @@ export class DefaultApiClient {
 
   /**
    * Get an entity by an entity ref.
-   * @param kind
-   * @param namespace
-   * @param name
+   * @param kind -
+   * @param namespace -
+   * @param name -
    */
   public async getEntityByName(
     // @ts-ignore
@@ -468,7 +469,7 @@ export class DefaultApiClient {
 
   /**
    * Get a single entity by the UID.
-   * @param uid
+   * @param uid -
    */
   public async getEntityByUid(
     // @ts-ignore
@@ -494,8 +495,8 @@ export class DefaultApiClient {
 
   /**
    * Get all entity facets that match the given filters.
-   * @param facet
-   * @param filter Filter for just the entities defined by this filter.
+   * @param facet -
+   * @param filter - Filter for just the entities defined by this filter.
    */
   public async getEntityFacets(
     // @ts-ignore
@@ -521,7 +522,7 @@ export class DefaultApiClient {
 
   /**
    * Get a location by id.
-   * @param id
+   * @param id -
    */
   public async getLocation(
     // @ts-ignore
@@ -547,9 +548,9 @@ export class DefaultApiClient {
 
   /**
    * Get a location for entity.
-   * @param kind
-   * @param namespace
-   * @param name
+   * @param kind -
+   * @param namespace -
+   * @param name -
    */
   public async getLocationByEntity(
     // @ts-ignore
@@ -600,7 +601,7 @@ export class DefaultApiClient {
 
   /**
    * Refresh the entity related to entityRef.
-   * @param refreshEntityRequest
+   * @param refreshEntityRequest -
    */
   public async refreshEntity(
     // @ts-ignore
@@ -625,7 +626,7 @@ export class DefaultApiClient {
 
   /**
    * Validate that a passed in entity has no errors in schema.
-   * @param validateEntityRequest
+   * @param validateEntityRequest -
    */
   public async validateEntity(
     // @ts-ignore

packages/repo-tools/templates/typescript-backstage-client/api.mustache

@@ -65,6 +65,7 @@ export type {{#lambda.pascalcase}}{{nickname}}{{/lambda.pascalcase}} = {
 
 /**
  * {{{description}}}{{^description}}no description{{/description}}
+ * @public
  */
 export class {{classname}}Client {
     private readonly discoveryApi: DiscoveryApi;
@@ -87,7 +88,7 @@ export class {{classname}}Client {
      * {{&summary}}
      {{/summary}}
      {{#allParams}}
-     * @param {{paramName}} {{description}}
+     * @param {{paramName}} - {{description}}
      {{/allParams}}
      */
     public async {{nickname}}(