Add new @tagMetadata decorator to OpenAPI library

.chronus/changes/tagMetadata-2024-9-23-12-55-56.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Add support for `@tagMetadata` decorator

.chronus/changes/tagMetadata-2024-9-31-13-14-32.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi"
+---
+
+Add new `@tagMetadata` decorator to specify OpenAPI tag properties

packages/openapi/README.md

@@ -17,6 +17,7 @@ npm install @typespec/openapi
 - [`@externalDocs`](#@externaldocs)
 - [`@info`](#@info)
 - [`@operationId`](#@operationid)
+- [`@tagMetadata`](#@tagmetadata)
 
 #### `@defaultResponse`
 
@@ -148,3 +149,22 @@ Specify the OpenAPI `operationId` property for this operation.
 @operationId("download")
 op read(): string;
 ```
+
+#### `@tagMetadata`
+
+Specify OpenAPI additional information.
+
+```typespec
+@TypeSpec.OpenAPI.tagMetadata(name: valueof string, tagMetadata?: TypeSpec.OpenAPI.TagMetadata)
+```
+
+##### Target
+
+`Namespace`
+
+##### Parameters
+
+| Name        | Type                          | Description |
+| ----------- | ----------------------------- | ----------- |
+| name        | `valueof string`              | tag name    |
+| tagMetadata | [`TagMetadata`](#tagmetadata) |             |

packages/openapi/generated-defs/TypeSpec.OpenAPI.ts

@@ -1,5 +1,15 @@
 import type { DecoratorContext, Model, Namespace, Operation, Type } from "@typespec/compiler";
 
+export interface TagMetadata {
+  readonly description?: string;
+  readonly externalDocs?: ExternalDocs;
+}
+
+export interface ExternalDocs {
+  readonly url: string;
+  readonly description?: string;
+}
+
 /**
  * Specify the OpenAPI `operationId` property for this operation.
  *
@@ -79,10 +89,25 @@ export type InfoDecorator = (
   additionalInfo: Type,
 ) => void;
 
+/**
+ * Specify OpenAPI additional information.
+ *
+ * @param name tag name
+ * @param tagMetadata Additional information
+ */
+export type TagMetadataDecorator = (
+  context: DecoratorContext,
+  target: Namespace,
+  name: string,
+  tagMetadata?: Type,
+  additional?: TagMetadata,
+) => void;
+
 export type TypeSpecOpenAPIDecorators = {
   operationId: OperationIdDecorator;
   extension: ExtensionDecorator;
   defaultResponse: DefaultResponseDecorator;
   externalDocs: ExternalDocsDecorator;
   info: InfoDecorator;
+  tagMetadata: TagMetadataDecorator;
 };

packages/openapi/lib/decorators.tsp

@@ -109,3 +109,33 @@ model License {
  * @param additionalInfo Additional information
  */
 extern dec info(target: Namespace, additionalInfo: AdditionalInfo);
+
+/** Metadata to a single tag that is used by operations. */
+model TagMetadata {
+  /** A description of the API. */
+  description?: string;
+
+  /** An external Docs information of the API. */
+  externalDocs?: ExternalDocs;
+}
+
+/** External Docs information. */
+model ExternalDocs {
+  /** Documentation url */
+  url: string;
+
+  /** Optional description */
+  description?: string;
+}
+
+/**
+ * Specify OpenAPI additional information.
+ * @param name tag name
+ * @param tagMetadata Additional information
+ */
+extern dec tagMetadata(
+  target: Namespace,
+  name: valueof string,
+  tagMetadata?: TagMetadata,
+  additional?: valueof TagMetadata
+);

packages/openapi/src/decorators.ts

@@ -1,10 +1,7 @@
 import {
-  compilerAssert,
+  $service,
   DecoratorContext,
-  Diagnostic,
-  DiagnosticTarget,
   getDoc,
-  getProperty,
   getService,
   getSummary,
   Model,
@@ -15,15 +12,19 @@ import {
   typespecTypeToJson,
   TypeSpecValue,
 } from "@typespec/compiler";
+import { unsafe_useStateMap } from "@typespec/compiler/experimental";
 import { setStatusCode } from "@typespec/http";
 import {
   DefaultResponseDecorator,
   ExtensionDecorator,
   ExternalDocsDecorator,
   InfoDecorator,
   OperationIdDecorator,
+  TagMetadata,
+  TagMetadataDecorator,
 } from "../generated-defs/TypeSpec.OpenAPI.js";
-import { createDiagnostic, createStateSymbol, reportDiagnostic } from "./lib.js";
+import { isOpenAPIExtensionKey, validateAdditionalInfoModel, validateIsUri } from "./helpers.js";
+import { createStateSymbol, OpenAPIKeys, reportDiagnostic } from "./lib.js";
 import { AdditionalInfo, ExtensionKey, ExternalDocs } from "./types.js";
 
 const operationIdsKey = createStateSymbol("operationIds");
@@ -114,10 +115,6 @@ export function getExtensions(program: Program, entity: Type): ReadonlyMap<Exten
   return program.stateMap(openApiExtensionKey).get(entity) ?? new Map<ExtensionKey, any>();
 }
 
-function isOpenAPIExtensionKey(key: string): key is ExtensionKey {
-  return key.startsWith("x-");
-}
-
 /**
  * The @defaultResponse decorator can be applied to a model. When that model is used
  * as the return type of an operation, this return type will be the default response.
@@ -189,9 +186,29 @@ export const $info: InfoDecorator = (
   if (data === undefined) {
     return;
   }
-  validateAdditionalInfoModel(context, model);
+
+  // Validate the AdditionalInfo model
+  if (
+    !validateAdditionalInfoModel(
+      context.program,
+      context.getArgumentTarget(0)!,
+      model as Model,
+      "TypeSpec.OpenAPI.AdditionalInfo",
+    )
+  ) {
+    return;
+  }
+
+  // Validate termsOfService
   if (data.termsOfService) {
-    if (!validateIsUri(context, data.termsOfService, "TermsOfService")) {
+    if (
+      !validateIsUri(
+        context.program,
+        context.getArgumentTarget(0)!,
+        data.termsOfService,
+        "TermsOfService",
+      )
+    ) {
       return;
     }
   }
@@ -225,64 +242,102 @@ function omitUndefined<T extends Record<string, unknown>>(data: T): T {
   return Object.fromEntries(Object.entries(data).filter(([k, v]) => v !== undefined)) as any;
 }
 
-function validateIsUri(context: DecoratorContext, url: string, propertyName: string) {
-  try {
-    new URL(url);
-    return true;
-  } catch {
+/** Get TagsMetadata set with `@tagMetadata` decorator */
+const [getTagsMetadata, setTagsMetadata] = unsafe_useStateMap<
+  Type,
+  { [name: string]: TagMetadata }
+>(OpenAPIKeys.tagsMetadata);
+
+/**
+ * Decorator to add metadata to a tag associated with a namespace.
+ * @param context - The decorator context.
+ * @param entity - The namespace entity to associate the tag with.
+ * @param name - The name of the tag.
+ * @param tagMetadata - Optional metadata for the tag.
+ */
+export const tagMetadataDecorator: TagMetadataDecorator = (
+  context: DecoratorContext,
+  entity: Namespace,
+  name: string,
+  tagMetadata?: TypeSpecValue,
+) => {
+  // Check if the namespace is a service namespace
+  if (!entity.decorators.some((decorator) => decorator.decorator === $service)) {
     reportDiagnostic(context.program, {
-      code: "not-url",
+      code: "tag-metadata-target-service",
+      format: {
+        namespace: entity.name,
+      },
       target: context.getArgumentTarget(0)!,
-      format: { property: propertyName, value: url },
     });
-    return false;
+    return;
+  }
+
+  // Retrieve existing tags metadata or initialize an empty object
+  const tags = getTagsMetadata(context.program, entity) ?? {};
+
+  // Check for duplicate tag names
+  if (tags[name]) {
+    reportDiagnostic(context.program, {
+      code: "duplicate-tag",
+      format: { tagName: name },
+      target: context.getArgumentTarget(0)!,
+    });
+    return;
   }
-}
 
-function validateAdditionalInfoModel(context: DecoratorContext, typespecType: TypeSpecValue) {
-  const propertyModel = context.program.resolveTypeReference(
-    "TypeSpec.OpenAPI.AdditionalInfo",
-  )[0]! as Model;
+  // Initialize metadata with the tag name
+  let metadata: TagMetadata = {};
 
-  if (typeof typespecType === "object" && propertyModel) {
-    const diagnostics = checkNoAdditionalProperties(
-      typespecType,
+  // Process tag metadata if provided
+  if (tagMetadata) {
+    // Convert TypeSpecValue to JSON and capture diagnostics
+    const [data, diagnostics] = typespecTypeToJson<TagMetadata & Record<ExtensionKey, unknown>>(
+      tagMetadata,
       context.getArgumentTarget(0)!,
-      propertyModel,
     );
+
+    // Report any diagnostics found during conversion
     context.program.reportDiagnostics(diagnostics);
-  }
-}
 
-function checkNoAdditionalProperties(
-  typespecType: Type,
-  target: DiagnosticTarget,
-  source: Model,
-): Diagnostic[] {
-  const diagnostics: Diagnostic[] = [];
-  compilerAssert(typespecType.kind === "Model", "Expected type to be a Model.");
-
-  for (const [name, type] of typespecType.properties.entries()) {
-    const sourceProperty = getProperty(source, name);
-    if (sourceProperty) {
-      if (sourceProperty.type.kind === "Model") {
-        const nestedDiagnostics = checkNoAdditionalProperties(
-          type.type,
-          target,
-          sourceProperty.type,
-        );
-        diagnostics.push(...nestedDiagnostics);
+    // Abort if data conversion failed
+    if (data === undefined) {
+      return;
+    }
+
+    // Validate the additionalInfo model
+    if (
+      !validateAdditionalInfoModel(
+        context.program,
+        context.getArgumentTarget(0)!,
+        tagMetadata as Model,
+        "TypeSpec.OpenAPI.TagMetadata",
+      )
+    ) {
+      return;
+    }
+
+    // Validate the externalDocs.url property
+    if (data.externalDocs?.url) {
+      if (
+        !validateIsUri(
+          context.program,
+          context.getArgumentTarget(0)!,
+          data.externalDocs.url,
+          "externalDocs.url",
+        )
+      ) {
+        return;
       }
-    } else if (!isOpenAPIExtensionKey(name)) {
-      diagnostics.push(
-        createDiagnostic({
-          code: "invalid-extension-key",
-          format: { value: name },
-          target,
-        }),
-      );
     }
+
+    // Merge data into metadata
+    metadata = { ...data };
   }
 
-  return diagnostics;
-}
+  // Update the tags metadata with the new tag
+  tags[name] = metadata;
+  setTagsMetadata(context.program, entity, tags);
+};
+
+export { getTagsMetadata };