chore(api): small improvements (#3707)

Author: tothandras

api/spec/lib/rules/friendly-name.js

@@ -12,6 +12,7 @@ export const friendlyNameRule = createRule({
       if (
         node.name &&
         !node.name.endsWith('Operations') &&
+        !node.name.endsWith('Endpoints') &&
         !node.decorators.some((d) => d.decorator.name === '$friendlyName')
       ) {
         context.reportDiagnostic({

api/spec/src/v3/common/error.tsp

@@ -119,9 +119,4 @@ model NotAvailable {
   @statusCode _: 503;
 }
 
-alias ErrorResponses =
-  | BadRequest
-  | Unauthorized
-  | Forbidden
-  | Internal
-  | NotAvailable;
+alias ErrorResponses = BadRequest | Unauthorized | Forbidden;

api/spec/src/v3/customers/operations.tsp

@@ -25,35 +25,6 @@ model ListCustomersParamsFilter {
   key?: Shared.ExternalResourceKey;
 }
 
-/**
- * Query params for listing customers.
- */
-@friendlyName("ListCustomersParams")
-model ListCustomersParams {
-  ...Common.PagePaginationQuery;
-
-  /**
-   * Sort customers returned in the response.
-   * Supported sort attributes are:
-   * - `id`
-   * - `name` (default)
-   * - `created_at`
-   *
-   * The `asc` suffix is optional as the default sort order is ascending.
-   * The `desc` suffix is used to specify a descending order.
-   */
-  @query(#{ name: "sort" })
-  sort?: Common.SortQuery;
-
-  /**
-   * Filter customers returned in the response.
-   *
-   * To filter customers by key add the following query param: filter[key]=my-db-id
-   */
-  @query(#{ style: "deepObject", explode: true })
-  filter?: ListCustomersParamsFilter;
-}
-
 interface CustomersOperations {
   @post
   @operationId("create-customer")
@@ -80,7 +51,28 @@ interface CustomersOperations {
   @extension(Shared.UnstableExtension, true)
   @extension(Shared.InternalExtension, true)
   list(
-    ...ListCustomersParams,
+    ...Common.PagePaginationQuery,
+
+    /**
+     * Sort customers returned in the response.
+     * Supported sort attributes are:
+     * - `id`
+     * - `name` (default)
+     * - `created_at`
+     *
+     * The `asc` suffix is optional as the default sort order is ascending.
+     * The `desc` suffix is used to specify a descending order.
+     */
+    @query(#{ name: "sort" })
+    sort?: Common.SortQuery,
+
+    /**
+     * Filter customers returned in the response.
+     *
+     * To filter customers by key add the following query param: filter[key]=my-db-id
+     */
+    @query(#{ style: "deepObject", explode: true })
+    filter?: ListCustomersParamsFilter,
   ): Shared.PagePaginatedResponse<Customer> | Common.ErrorResponses;
 
   @put

api/spec/src/v3/konnect.tsp

@@ -44,29 +44,23 @@ namespace MeteringAndBilling;
 
 @route("/openmeter/events")
 @tag(Shared.EventsTag)
-@friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.EventsTag}")
 interface EventsEndpoints extends Events.EventsOperations {}
 
 @route("/openmeter/meters")
 @tag(Shared.MetersTag)
-@friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.MetersTag}")
 interface MetersEndpoints extends Meters.MetersOperations {}
 
 @route("/openmeter/customers")
 @tag(Shared.CustomersTag)
-@friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.CustomersTag}")
 interface CustomersEndpoints extends Customers.CustomersOperations {}
 
 @route("/openmeter/customers/{customerId}/entitlement-access")
-@tag(Shared.CustomersTag)
 @tag(Shared.EntitlementsTag)
-@friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.EntitlementsTag}")
 interface CustomerEntitlementsEndpoints
   extends Entitlements.CustomerEntitlementsOperations {}
 
 @route("/openmeter/subscriptions")
 @tag(Shared.SubscriptionsTag)
-@friendlyName("${Shared.MeteringAndBillingTitle}: ${Shared.SubscriptionsTag}")
 interface SubscriptionsEndpoints
   extends Subscriptions.SubscriptionsOperations {}
 

api/spec/src/v3/openmeter.tsp

@@ -40,28 +40,22 @@ namespace OpenMeter;
 
 @route("/openmeter/events")
 @tag(Shared.EventsTag)
-@friendlyName("${Shared.OpenMeterTitle}: ${Shared.EventsTag}")
 interface EventsEndpoints extends Events.EventsOperations {}
 
 @route("/openmeter/meters")
 @tag(Shared.MetersTag)
-@friendlyName("${Shared.OpenMeterTitle}: ${Shared.MetersTag}")
 interface MetersEndpoints extends Meters.MetersOperations {}
 
 @route("/openmeter/customers")
 @tag(Shared.CustomersTag)
-@friendlyName("${Shared.OpenMeterTitle}: ${Shared.CustomersTag}")
 interface CustomersEndpoints extends Customers.CustomersOperations {}
 
 @route("/openmeter/customers/{customerId}/entitlement-access")
-@tag(Shared.CustomersTag)
 @tag(Shared.EntitlementsTag)
-@friendlyName("${Shared.OpenMeterTitle}: ${Shared.EntitlementsTag}")
 interface CustomerEntitlementsEndpoints
   extends Entitlements.CustomerEntitlementsOperations {}
 
 @route("/openmeter/subscriptions")
 @tag(Shared.SubscriptionsTag)
-@friendlyName("${Shared.OpenMeterTitle}: ${Shared.SubscriptionsTag}")
 interface SubscriptionsEndpoints
   extends Subscriptions.SubscriptionsOperations {}

api/spec/src/v3/subscriptions/operations.tsp

@@ -12,37 +12,6 @@ using TypeSpec.OpenAPI;
 
 namespace Subscriptions;
 
-/**
- * Query params for listing subscriptions.
- */
-@friendlyName("ListSubscriptionsParams")
-model ListSubscriptionsParams {
-  ...Common.PagePaginationQuery;
-
-  /**
-   * Sort subscriptions returned in the response.
-   * Supported sort attributes are:
-   * - `id`
-   * - `created_at`
-   *
-   * The `asc` suffix is optional as the default sort order is ascending.
-   * The `desc` suffix is used to specify a descending order.
-   */
-  @query(#{ name: "sort" })
-  sort?: Common.SortQuery;
-
-  /**
-   * Filter subscriptions.
-   */
-  @query(#{ style: "deepObject", explode: true })
-  filter?: {
-    /**
-     * Filter subscriptions by customer ID.
-     */
-    customer_id?: Shared.ULID;
-  };
-}
-
 /**
  * Request for canceling a subscription.
  */
@@ -102,7 +71,18 @@ interface SubscriptionsOperations {
   @extension(Shared.UnstableExtension, true)
   @extension(Shared.InternalExtension, true)
   list(
-    ...ListSubscriptionsParams,
+    ...Common.PagePaginationQuery,
+
+    /**
+     * Filter subscriptions.
+     */
+    @query(#{ style: "deepObject", explode: true })
+    filter?: {
+      /**
+       * Filter subscriptions by customer ID.
+       */
+      customer_id?: Shared.ULID;
+    },
   ): Shared.PagePaginatedResponse<Subscription> | Common.NotFound | Common.ErrorResponses;
 
   @get

api/spec/src/v3/subscriptions/subscription.tsp

@@ -33,6 +33,7 @@ enum SubscriptionEditTimingEnum {
  */
 @oneOf
 @friendlyName("BillingSubscriptionEditTiming")
+@example(SubscriptionEditTimingEnum.immediate)
 union SubscriptionEditTiming {
   Enum: SubscriptionEditTimingEnum,
   Custom: Shared.DateTime,