@summary sets the title of definitions (#813)

fix [#289](#289) --------- Co-authored-by: Mark Cowlishaw <[email protected]>
Azure · May 21, 2024 · 81d679f · 81d679f
1 parent e2bb305
commit 81d679f
Show file tree

Hide file tree

Showing 4 changed files with 48 additions and 10 deletions.
diff --git a/.chronus/changes/summary-is-title-2024-4-9-20-35-33.md b/.chronus/changes/summary-is-title-2024-4-9-20-35-33.md
@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-autorest"
+---
+
+`@summary` sets the title of definitions
diff --git a/packages/typespec-autorest/src/openapi.ts b/packages/typespec-autorest/src/openapi.ts
@@ -43,6 +43,7 @@ import {
   Value,
   compilerAssert,
   createDiagnosticCollector,
+  explainStringTemplateNotSerializable,
   getAllTags,
   getDirectoryPath,
   getDiscriminator,
@@ -84,7 +85,6 @@ import {
   navigateTypesInNamespace,
   resolveEncodedName,
   resolvePath,
-  stringTemplateToString,
 } from "@typespec/compiler";
 import { TwoLevelMap } from "@typespec/compiler/utils";
 import {
@@ -1566,7 +1566,7 @@ export async function getOpenAPIForService(
         modelSchema.required = [propertyName];
       }
     }
-
+    applySummary(model, modelSchema);
     applyExternalDocs(model, modelSchema);
 
     for (const prop of model.properties.values()) {
@@ -1589,7 +1589,6 @@ export async function getOpenAPIForService(
       const clientName = getClientName(context, prop);
 
       const description = getDoc(program, prop);
-
       // if this property is a discriminator property, remove it to keep autorest validation happy
       if (model.baseModel) {
         const { propertyName } = getDiscriminator(program, model.baseModel) || {};
@@ -1617,6 +1616,7 @@ export async function getOpenAPIForService(
       if (description) {
         property.description = description;
       }
+      applySummary(prop, property);
 
       if (prop.defaultValue && !("$ref" in property)) {
         property.default = getDefaultValue(prop.defaultValue);
@@ -1690,9 +1690,9 @@ export async function getOpenAPIForService(
 
   function resolveProperty(prop: ModelProperty, context: SchemaContext): OpenAPI2SchemaProperty {
     let propSchema;
-    if (prop.type.kind === "Enum" && prop.default) {
+    if (prop.type.kind === "Enum" && prop.defaultValue) {
       propSchema = getSchemaForEnum(prop.type);
-    } else if (prop.type.kind === "Union" && prop.default) {
+    } else if (prop.type.kind === "Union" && prop.defaultValue) {
       const [asEnum, _] = getUnionAsEnum(prop.type);
       if (asEnum) {
         propSchema = getSchemaForUnionEnum(prop.type, asEnum);
@@ -1758,6 +1758,11 @@ export async function getOpenAPIForService(
       newTarget.description = docStr;
     }
 
+    const title = getSummary(program, typespecType);
+    if (title) {
+      target.title = title;
+    }
+
     const formatStr = getFormat(program, typespecType);
     if (isString && formatStr) {
       const allowedStringFormats = [
@@ -1903,6 +1908,12 @@ export async function getOpenAPIForService(
     }
   }
 
+  function applySummary(typespecType: Type, target: { title?: string }) {
+    const summary = getSummary(program, typespecType);
+    if (summary) {
+      target.title = summary;
+    }
+  }
   function applyExternalDocs(typespecType: Type, target: Record<string, unknown>) {
     const externalDocs = getExternalDocs(program, typespecType);
     if (externalDocs) {
@@ -1949,12 +1960,16 @@ export async function getOpenAPIForService(
   }
 
   function getSchemaForStringTemplate(stringTemplate: StringTemplate) {
-    const [value, diagnostics] = stringTemplateToString(stringTemplate);
-    if (diagnostics.length > 0) {
-      program.reportDiagnostics(diagnostics.map((x) => ({ ...x, severity: "warning" })));
+    if (stringTemplate.stringValue === undefined) {
+      program.reportDiagnostics(
+        explainStringTemplateNotSerializable(stringTemplate).map((x) => ({
+          ...x,
+          severity: "warning",
+        }))
+      );
       return { type: "string" };
     }
-    return { type: "string", enum: [value] };
+    return { type: "string", enum: [stringTemplate.stringValue] };
   }
   // Map an TypeSpec type to an OA schema. Returns undefined when the resulting
   // OA schema is just a regular object schema.

diff --git a/packages/typespec-autorest/src/openapi2-document.ts b/packages/typespec-autorest/src/openapi2-document.ts
@@ -110,7 +110,7 @@ export type JsonType = "array" | "boolean" | "integer" | "number" | "object" | "
  * Autorest allows a few properties to be next to $ref of a property.
  */
 export type OpenAPI2SchemaRefProperty = Ref<OpenAPI2Schema> &
-  Pick<OpenAPI2Schema, "readOnly" | "description" | "default" | "x-ms-mutability"> & {
+  Pick<OpenAPI2Schema, "readOnly" | "description" | "default" | "x-ms-mutability" | "title"> & {
     /**
      * Provide a different name to be used in the client.
      */

diff --git a/packages/typespec-autorest/test/models.test.ts b/packages/typespec-autorest/test/models.test.ts
@@ -90,6 +90,21 @@ describe("typespec-autorest: model definitions", () => {
     });
   });
 
+  it("using @summary sets the title on definitions and properties", async () => {
+    const res = await oapiForModel(
+      "Foo",
+      `
+      @summary("FooModel")
+      model Foo {
+        @summary("YProp")
+        y: int32;
+      };
+      `
+    );
+    strictEqual(res.defs.Foo.title, "FooModel");
+    strictEqual(res.defs.Foo.properties.y.title, "YProp");
+  });
+
   it("uses json name specified via @encodedName", async () => {
     const res = await oapiForModel(
       "Foo",