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 new file mode 100644 index 0000000000..73a41a6c3e --- /dev/null +++ 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 index 10878db185..f366ec95e3 100644 --- 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) { 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 index c87a8cd2dd..fba900eabd 100644 --- 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 & - Pick & { + Pick & { /** * 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 index 42337fc209..0917935912 100644 --- 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",