From 5ceabf7561841ae6399ab2ff41ac3bd871ae9766 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 13:26:52 -0800 Subject: [PATCH 01/24] Show properties --- .../libraries/openapi/reference/data-types.md | 23 ++++ .../libraries/openapi/reference/decorators.md | 12 +- packages/openapi/README.md | 12 +- .../tspd/src/ref-doc/emitters/markdown.ts | 35 ++++-- packages/tspd/src/ref-doc/extractor.ts | 49 +++++++- packages/tspd/src/ref-doc/types.ts | 115 ++++++++++-------- 6 files changed, 169 insertions(+), 77 deletions(-) diff --git a/docs/libraries/openapi/reference/data-types.md b/docs/libraries/openapi/reference/data-types.md index 0a0fd0d0b5..947ea60ef2 100644 --- a/docs/libraries/openapi/reference/data-types.md +++ b/docs/libraries/openapi/reference/data-types.md @@ -16,6 +16,14 @@ Additional information for the OpenAPI document. model TypeSpec.OpenAPI.AdditionalInfo ``` +#### Properties + +| Name | Type | Description | +| -------------- | --------- | -------------------------------------------------------------------------------- | +| termsOfService | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
| +| contact | `Contact` | The contact information for the exposed API.
| +| license | `License` | The license information for the exposed API.
| + ### `Contact` {#TypeSpec.OpenAPI.Contact} Contact information for the exposed API. @@ -24,6 +32,14 @@ Contact information for the exposed API. model TypeSpec.OpenAPI.Contact ``` +#### Properties + +| Name | Type | Description | +| ----- | -------- | ------------------------------------------------------------------------------------------------------ | +| name | `string` | The identifying name of the contact person/organization.
| +| url | `url` | The URL pointing to the contact information. MUST be in the format of a URL.
| +| email | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
| + ### `License` {#TypeSpec.OpenAPI.License} License information for the exposed API. @@ -31,3 +47,10 @@ License information for the exposed API. ```typespec model TypeSpec.OpenAPI.License ``` + +#### Properties + +| Name | Type | Description | +| ---- | -------- | ---------------------------------------------------------------------------- | +| name | `string` | The license name used for the API.
| +| url | `url` | A URL to the license used for the API. MUST be in the format of a URL.
| diff --git a/docs/libraries/openapi/reference/decorators.md b/docs/libraries/openapi/reference/decorators.md index 44ae2d91da..4bb0d388c1 100644 --- a/docs/libraries/openapi/reference/decorators.md +++ b/docs/libraries/openapi/reference/decorators.md @@ -44,14 +44,14 @@ Attach some custom data to the OpenAPI element generated from this type. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | | ----- | ----------------------- | ----------------------------------- | | key | `valueof scalar string` | Extension key. Must start with `x-` | -| value | `(intrinsic) unknown` | Extension value. | +| value | `unknown` | Extension value. | #### Examples @@ -76,7 +76,7 @@ Specify the OpenAPI `externalDocs` property for this type. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters @@ -110,9 +110,9 @@ The service `title` and `version` are already specified using `@service`. #### Parameters -| Name | Type | Description | -| -------------- | --------------------------------------- | ---------------------- | -| additionalInfo | `model TypeSpec.OpenAPI.AdditionalInfo` | Additional information | +| Name | Type | Description | +| -------------- | ---------------- | ---------------------- | +| additionalInfo | `AdditionalInfo` | Additional information | ### `@operationId` {#@TypeSpec.OpenAPI.operationId} diff --git a/packages/openapi/README.md b/packages/openapi/README.md index 05e3b1e9e6..80b91b0761 100644 --- a/packages/openapi/README.md +++ b/packages/openapi/README.md @@ -54,14 +54,14 @@ Attach some custom data to the OpenAPI element generated from this type. ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters | Name | Type | Description | | ----- | ----------------------- | ----------------------------------- | | key | `valueof scalar string` | Extension key. Must start with `x-` | -| value | `(intrinsic) unknown` | Extension value. | +| value | `unknown` | Extension value. | ##### Examples @@ -86,7 +86,7 @@ Specify the OpenAPI `externalDocs` property for this type. ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters @@ -120,9 +120,9 @@ The service `title` and `version` are already specified using `@service`. ##### Parameters -| Name | Type | Description | -| -------------- | --------------------------------------- | ---------------------- | -| additionalInfo | `model TypeSpec.OpenAPI.AdditionalInfo` | Additional information | +| Name | Type | Description | +| -------------- | ---------------- | ---------------------- | +| additionalInfo | `AdditionalInfo` | Additional information | #### `@operationId` diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 9bd8eab608..30d043376e 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -1,4 +1,4 @@ -import { resolvePath } from "@typespec/compiler"; +import { Type, ValueType, resolvePath } from "@typespec/compiler"; import { readFile } from "fs/promises"; import { stringify } from "yaml"; import { @@ -72,7 +72,7 @@ export async function renderReadme(refDoc: TypeSpecRefDoc, projectRoot: string) } export function groupByNamespace( - namespaces: NamespaceRefDoc[], + namespaces: readonly NamespaceRefDoc[], callback: (namespace: NamespaceRefDoc) => MarkdownDoc | undefined ): MarkdownDoc { const content: MarkdownDoc = []; @@ -136,10 +136,29 @@ export class MarkdownRenderer { } content.push(this.examples(model.examples)); - + content.push(this.modelProperties(model)); return section(this.headingTitle(model), content); } + modelProperties(model: ModelRefDoc) { + const content: MarkdownDoc = []; + content.push( + table([ + ["Name", "Type", "Description"], + ...[...model.properties.values()].map((prop) => { + return [prop.name, inlinecode(this.ref(prop.type.type)), prop.doc]; + }), + ]) + ); + return section("Properties", content); + } + + ref(type: Type | ValueType): string { + return "name" in type && typeof type.name === "string" + ? inlinecode(type.name) + : getTypeSignature(type); + } + enum(e: EnumRefDoc): MarkdownDoc { const content: MarkdownDoc = [ "", @@ -176,7 +195,7 @@ export class MarkdownRenderer { return section(this.headingTitle(scalar), content); } - templateParameters(templateParameters: TemplateParameterRefDoc[]): MarkdownDoc { + templateParameters(templateParameters: readonly TemplateParameterRefDoc[]): MarkdownDoc { const paramTable: string[][] = [["Name", "Description"]]; for (const param of templateParameters) { paramTable.push([param.name, param.doc]); @@ -189,13 +208,13 @@ export class MarkdownRenderer { const content: MarkdownDoc = ["", dec.doc, codeblock(dec.signature, "typespec"), ""]; content.push( - section("Target", [dec.target.doc, inlinecode(getTypeSignature(dec.target.type.type)), ""]) + section("Target", [dec.target.doc, inlinecode(this.ref(dec.target.type.type)), ""]) ); if (dec.parameters.length > 0) { const paramTable: string[][] = [["Name", "Type", "Description"]]; for (const param of dec.parameters) { - paramTable.push([param.name, inlinecode(getTypeSignature(param.type.type)), param.doc]); + paramTable.push([param.name, inlinecode(this.ref(param.type.type)), param.doc]); } content.push(section("Parameters", [table(paramTable), ""])); } else { @@ -207,7 +226,7 @@ export class MarkdownRenderer { return section(this.headingTitle(dec), content); } - examples(examples: ExampleRefDoc[]) { + examples(examples: readonly ExampleRefDoc[]) { const content: MarkdownDoc = []; if (examples.length === 0) { return ""; @@ -241,7 +260,7 @@ export class MarkdownRenderer { }); } - toc(items: ReferencableElement[], filename?: string) { + toc(items: readonly ReferencableElement[], filename?: string) { return items.map( (item) => ` - [${inlinecode(item.name)}](${filename ?? ""}#${this.anchorId(item)})` ); diff --git a/packages/tspd/src/ref-doc/extractor.ts b/packages/tspd/src/ref-doc/extractor.ts index 4e6e7f172e..2d2cef3ca1 100644 --- a/packages/tspd/src/ref-doc/extractor.ts +++ b/packages/tspd/src/ref-doc/extractor.ts @@ -20,6 +20,7 @@ import { LinterRuleDefinition, LinterRuleSet, Model, + ModelProperty, Namespace, navigateProgram, navigateTypesInNamespace, @@ -49,6 +50,7 @@ import { LinterRefDoc, LinterRuleRefDoc, LinterRuleSetRefDoc, + ModelPropertyRefDoc, ModelRefDoc, NamespaceRefDoc, OperationRefDoc, @@ -59,12 +61,34 @@ import { } from "./types.js"; import { getQualifier, getTypeSignature } from "./utils/type-signature.js"; +/** + * The mutable equivalent of a type. + */ + +//prettier-ignore +type MutableArrayProps = + T extends ReadonlyMap ? Map : + T extends ReadonlySet ? Set> : + T extends readonly (infer V)[] ? V[] : + // brand to force explicit conversion. + { -readonly [P in keyof T]: MutateIfArray }; + +//prettier-ignore +type Mutable = + T extends ReadonlyMap ? Map : + T extends ReadonlySet ? Set> : + T extends readonly (infer V)[] ? V[] : + // brand to force explicit conversion. + { -readonly [P in keyof T]: T[P]}; + +type MutateIfArray = T extends readonly (infer U)[] ? U[] : T; + export async function extractLibraryRefDocs( libraryPath: string ): Promise<[TypeSpecLibraryRefDoc, readonly Diagnostic[]]> { const diagnostics = createDiagnosticCollector(); const pkgJson = await readPackageJson(libraryPath); - const refDoc: TypeSpecLibraryRefDoc = { + const refDoc: Mutable = { name: pkgJson.name, description: pkgJson.description, packageJson: pkgJson, @@ -75,7 +99,7 @@ export async function extractLibraryRefDocs( const program = await compile(NodeHost, main, { parseOptions: { comments: true, docs: true }, }); - refDoc.namespaces = diagnostics.pipe(extractRefDocs(program)).namespaces; + refDoc.namespaces = diagnostics.pipe(extractRefDocs(program)).namespaces as any; for (const diag of program.diagnostics ?? []) { diagnostics.add(diag); } @@ -150,12 +174,12 @@ export function extractRefDocs( const diagnostics = createDiagnosticCollector(); const namespaceTypes = diagnostics.pipe(resolveNamespaces(program, options)); - const refDoc: TypeSpecRefDocBase = { + const refDoc: MutableArrayProps = { namespaces: [], }; for (const namespace of namespaceTypes) { - const namespaceDoc: NamespaceRefDoc = { + const namespaceDoc: MutableArrayProps = { id: getTypeName(namespace), decorators: [], operations: [], @@ -219,7 +243,7 @@ export function extractRefDocs( } sort(refDoc.namespaces); - for (const namespace of refDoc.namespaces) { + for (const namespace of refDoc.namespaces as MutableArrayProps[]) { sort(namespace.decorators); sort(namespace.enums); sort(namespace.interfaces); @@ -385,6 +409,21 @@ function extractModelRefDocs(program: Program, type: Model): ModelRefDoc { templateParameters: extractTemplateParameterDocs(program, type), doc: doc, examples: extractExamples(type), + properties: new Map( + [...type.properties.values()].map((x) => [x.name, extractModelPropertyRefDocs(program, x)]) + ), + }; +} + +function extractModelPropertyRefDocs(program: Program, type: ModelProperty): ModelPropertyRefDoc { + const doc = extractMainDoc(program, type); + return { + id: getNamedTypeId(type), + name: type.name, + signature: getTypeSignature(type), + type, + doc: doc, + examples: extractExamples(type), }; } diff --git a/packages/tspd/src/ref-doc/types.ts b/packages/tspd/src/ref-doc/types.ts index 842e05eedd..db61bc68d5 100644 --- a/packages/tspd/src/ref-doc/types.ts +++ b/packages/tspd/src/ref-doc/types.ts @@ -6,6 +6,7 @@ import { LinterRuleDefinition, LinterRuleSet, Model, + ModelProperty, NodePackage, Operation, Scalar, @@ -18,133 +19,143 @@ export type TypeSpecLibraryRefDoc = TypeSpecRefDocBase & { /** * Library name */ - name: string; + readonly name: string; /** * Library package.json */ - packageJson: NodePackage; + readonly packageJson: NodePackage; /** * Library description */ - description?: string; + readonly description?: string; - emitter?: EmitterRefDoc; + readonly emitter?: EmitterRefDoc; /** Documentation about the linter rules and ruleset provided in this library. */ - linter?: LinterRefDoc; + readonly linter?: LinterRefDoc; }; export type TypeSpecRefDocBase = { - namespaces: NamespaceRefDoc[]; + readonly namespaces: readonly NamespaceRefDoc[]; }; export type EmitterRefDoc = { - options: EmitterOptionRefDoc[]; + readonly options: EmitterOptionRefDoc[]; }; export type LinterRefDoc = { /** List of rulesets provided. */ - ruleSets?: LinterRuleSetRefDoc[]; - rules: LinterRuleRefDoc[]; + readonly ruleSets?: LinterRuleSetRefDoc[]; + readonly rules: LinterRuleRefDoc[]; }; export type LinterRuleSetRefDoc = ReferencableElement & { - ruleSet: LinterRuleSet; + readonly ruleSet: LinterRuleSet; }; export type LinterRuleRefDoc = ReferencableElement & { - rule: LinterRuleDefinition; + readonly rule: LinterRuleDefinition; }; export type EmitterOptionRefDoc = { - name: string; - type: string; - doc: string; + readonly name: string; + readonly type: string; + readonly doc: string; }; export type NamespaceRefDoc = { - id: string; - decorators: DecoratorRefDoc[]; - operations: OperationRefDoc[]; - interfaces: InterfaceRefDoc[]; - models: ModelRefDoc[]; - enums: EnumRefDoc[]; - unions: UnionRefDoc[]; - scalars: ScalarRefDoc[]; + readonly id: string; + readonly decorators: readonly DecoratorRefDoc[]; + readonly operations: readonly OperationRefDoc[]; + readonly interfaces: readonly InterfaceRefDoc[]; + readonly models: readonly ModelRefDoc[]; + readonly enums: readonly EnumRefDoc[]; + readonly unions: readonly UnionRefDoc[]; + readonly scalars: readonly ScalarRefDoc[]; }; export type ReferencableElement = { /** * Fully qualified id */ - id: string; + readonly id: string; - name: string; + readonly name: string; }; export type NamedTypeRefDoc = ReferencableElement & { - signature: string; - doc: string; - examples: ExampleRefDoc[]; + readonly signature: string; + readonly doc: string; + readonly examples: readonly ExampleRefDoc[]; }; export type DecoratorRefDoc = NamedTypeRefDoc & { - type: Decorator; - target: FunctionParameterRefDoc; - parameters: FunctionParameterRefDoc[]; - otherTags: string[]; + readonly type: Decorator; + readonly target: FunctionParameterRefDoc; + readonly parameters: readonly FunctionParameterRefDoc[]; + readonly otherTags: readonly string[]; }; export type FunctionParameterRefDoc = { - type: FunctionParameter; - name: string; - doc: string; - optional: boolean; - rest: boolean; + readonly type: FunctionParameter; + readonly name: string; + readonly doc: string; + readonly optional: boolean; + readonly rest: boolean; }; export type ExampleRefDoc = { - title?: string; - content: string; + readonly title?: string; + readonly content: string; }; export type OperationRefDoc = NamedTypeRefDoc & { - type: Operation; + readonly type: Operation; - templateParameters?: TemplateParameterRefDoc[]; + readonly templateParameters?: TemplateParameterRefDoc[]; }; export type InterfaceRefDoc = NamedTypeRefDoc & { - type: Interface; - templateParameters?: TemplateParameterRefDoc[]; + readonly type: Interface; + readonly templateParameters?: readonly TemplateParameterRefDoc[]; - interfaceOperations: OperationRefDoc[]; + readonly interfaceOperations: readonly OperationRefDoc[]; }; export type TemplateParameterRefDoc = { - name: string; - doc: string; + readonly name: string; + readonly doc: string; }; export type ModelRefDoc = NamedTypeRefDoc & { - type: Model; + readonly type: Model; - templateParameters?: TemplateParameterRefDoc[]; + readonly templateParameters?: readonly TemplateParameterRefDoc[]; + readonly properties: ReadonlyMap; +}; + +export type ModelPropertyRefDoc = NamedTypeRefDoc & { + readonly type: ModelProperty; +}; + +export type TypeRefDocRef = { + id: string; + name: string; }; export type EnumRefDoc = NamedTypeRefDoc & { - type: Enum; + readonly type: Enum; }; export type UnionRefDoc = NamedTypeRefDoc & { - type: Union; + readonly type: Union; - templateParameters?: TemplateParameterRefDoc[]; + readonly templateParameters?: readonly TemplateParameterRefDoc[]; }; export type ScalarRefDoc = NamedTypeRefDoc & { - type: Scalar; + readonly type: Scalar; - templateParameters?: TemplateParameterRefDoc[]; + readonly templateParameters?: readonly TemplateParameterRefDoc[]; }; From 5e5bee4bbd6cd2a7c03328d2d0af18f23b53406c Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 13:57:01 -0800 Subject: [PATCH 02/24] Link to data types --- .../libraries/openapi/reference/data-types.md | 22 +++---- .../libraries/openapi/reference/decorators.md | 28 ++++---- packages/openapi/README.md | 28 ++++---- .../tspd/src/ref-doc/emitters/docusaurus.ts | 6 +- .../tspd/src/ref-doc/emitters/markdown.ts | 19 ++++-- packages/tspd/src/ref-doc/extractor.ts | 65 ++++++++++--------- packages/tspd/src/ref-doc/types.ts | 9 ++- 7 files changed, 94 insertions(+), 83 deletions(-) diff --git a/docs/libraries/openapi/reference/data-types.md b/docs/libraries/openapi/reference/data-types.md index 947ea60ef2..63480bbba2 100644 --- a/docs/libraries/openapi/reference/data-types.md +++ b/docs/libraries/openapi/reference/data-types.md @@ -18,11 +18,11 @@ model TypeSpec.OpenAPI.AdditionalInfo #### Properties -| Name | Type | Description | -| -------------- | --------- | -------------------------------------------------------------------------------- | -| termsOfService | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
| -| contact | `Contact` | The contact information for the exposed API.
| -| license | `License` | The license information for the exposed API.
| +| Name | Type | Description | +| --------------- | -------------------------------------- | -------------------------------------------------------------------------------- | +| termsOfService? | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
| +| contact? | [`Contact`](#TypeSpec.OpenAPI.Contact) | The contact information for the exposed API.
| +| license? | [`License`](#TypeSpec.OpenAPI.License) | The license information for the exposed API.
| ### `Contact` {#TypeSpec.OpenAPI.Contact} @@ -34,11 +34,11 @@ model TypeSpec.OpenAPI.Contact #### Properties -| Name | Type | Description | -| ----- | -------- | ------------------------------------------------------------------------------------------------------ | -| name | `string` | The identifying name of the contact person/organization.
| -| url | `url` | The URL pointing to the contact information. MUST be in the format of a URL.
| -| email | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
| +| Name | Type | Description | +| ------ | -------- | ------------------------------------------------------------------------------------------------------ | +| name? | `string` | The identifying name of the contact person/organization.
| +| url? | `url` | The URL pointing to the contact information. MUST be in the format of a URL.
| +| email? | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
| ### `License` {#TypeSpec.OpenAPI.License} @@ -53,4 +53,4 @@ model TypeSpec.OpenAPI.License | Name | Type | Description | | ---- | -------- | ---------------------------------------------------------------------------- | | name | `string` | The license name used for the API.
| -| url | `url` | A URL to the license used for the API. MUST be in the format of a URL.
| +| url? | `url` | A URL to the license used for the API. MUST be in the format of a URL.
| diff --git a/docs/libraries/openapi/reference/decorators.md b/docs/libraries/openapi/reference/decorators.md index 4bb0d388c1..3a999a99fd 100644 --- a/docs/libraries/openapi/reference/decorators.md +++ b/docs/libraries/openapi/reference/decorators.md @@ -48,10 +48,10 @@ Attach some custom data to the OpenAPI element generated from this type. #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------------------------------- | -| key | `valueof scalar string` | Extension key. Must start with `x-` | -| value | `unknown` | Extension value. | +| Name | Type | Description | +| ----- | --------------------- | ----------------------------------- | +| key | valueof scalar string | Extension key. Must start with `x-` | +| value | `unknown` | Extension value. | #### Examples @@ -80,10 +80,10 @@ Specify the OpenAPI `externalDocs` property for this type. #### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ----------------------- | -| url | `valueof scalar string` | Url to the docs | -| description | `valueof scalar string` | Description of the docs | +| Name | Type | Description | +| ----------- | --------------------- | ----------------------- | +| url | valueof scalar string | Url to the docs | +| description | valueof scalar string | Description of the docs | #### Examples @@ -110,9 +110,9 @@ The service `title` and `version` are already specified using `@service`. #### Parameters -| Name | Type | Description | -| -------------- | ---------------- | ---------------------- | -| additionalInfo | `AdditionalInfo` | Additional information | +| Name | Type | Description | +| -------------- | ---------------------------------------------------- | ---------------------- | +| additionalInfo | [`AdditionalInfo`](#TypeSpec.OpenAPI.AdditionalInfo) | Additional information | ### `@operationId` {#@TypeSpec.OpenAPI.operationId} @@ -128,9 +128,9 @@ Specify the OpenAPI `operationId` property for this operation. #### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------- | -| operationId | `valueof scalar string` | Operation id value. | +| Name | Type | Description | +| ----------- | --------------------- | ------------------- | +| operationId | valueof scalar string | Operation id value. | #### Examples diff --git a/packages/openapi/README.md b/packages/openapi/README.md index 80b91b0761..83ffdf1fd2 100644 --- a/packages/openapi/README.md +++ b/packages/openapi/README.md @@ -58,10 +58,10 @@ Attach some custom data to the OpenAPI element generated from this type. ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------------------------------- | -| key | `valueof scalar string` | Extension key. Must start with `x-` | -| value | `unknown` | Extension value. | +| Name | Type | Description | +| ----- | --------------------- | ----------------------------------- | +| key | valueof scalar string | Extension key. Must start with `x-` | +| value | `unknown` | Extension value. | ##### Examples @@ -90,10 +90,10 @@ Specify the OpenAPI `externalDocs` property for this type. ##### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ----------------------- | -| url | `valueof scalar string` | Url to the docs | -| description | `valueof scalar string` | Description of the docs | +| Name | Type | Description | +| ----------- | --------------------- | ----------------------- | +| url | valueof scalar string | Url to the docs | +| description | valueof scalar string | Description of the docs | ##### Examples @@ -120,9 +120,9 @@ The service `title` and `version` are already specified using `@service`. ##### Parameters -| Name | Type | Description | -| -------------- | ---------------- | ---------------------- | -| additionalInfo | `AdditionalInfo` | Additional information | +| Name | Type | Description | +| -------------- | ----------------------------------- | ---------------------- | +| additionalInfo | [`AdditionalInfo`](#additionalinfo) | Additional information | #### `@operationId` @@ -138,9 +138,9 @@ Specify the OpenAPI `operationId` property for this operation. ##### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------- | -| operationId | `valueof scalar string` | Operation id value. | +| Name | Type | Description | +| ----------- | --------------------- | ------------------- | +| operationId | valueof scalar string | Operation id value. | ##### Examples diff --git a/packages/tspd/src/ref-doc/emitters/docusaurus.ts b/packages/tspd/src/ref-doc/emitters/docusaurus.ts index 89c817f1c6..0dac032a73 100644 --- a/packages/tspd/src/ref-doc/emitters/docusaurus.ts +++ b/packages/tspd/src/ref-doc/emitters/docusaurus.ts @@ -255,10 +255,8 @@ function renderLinter( } export class DocusaurusRenderer extends MarkdownRenderer { - #refDoc: TypeSpecLibraryRefDoc; constructor(refDoc: TypeSpecLibraryRefDoc) { - super(); - this.#refDoc = refDoc; + super(refDoc); } headingTitle(item: NamedTypeRefDoc): string { // Set an explicit anchor id. @@ -288,7 +286,7 @@ export class DocusaurusRenderer extends MarkdownRenderer { } linterRuleLink(url: string) { - const homepage = (this.#refDoc.packageJson as any).docusaurusWebsite; + const homepage = (this.refDoc.packageJson as any).docusaurusWebsite; if (homepage && url.includes(homepage)) { const fromRoot = url.replace(homepage, ""); return `${fromRoot}.md`; diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 30d043376e..e60f13efc9 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -44,7 +44,7 @@ async function loadTemplate(projectRoot: string, name: string) { export async function renderReadme(refDoc: TypeSpecRefDoc, projectRoot: string) { const content: MarkdownDoc[] = []; - const renderer = new MarkdownRenderer(); + const renderer = new MarkdownRenderer(refDoc); if (refDoc.description) { content.push(refDoc.description); @@ -89,6 +89,7 @@ export function groupByNamespace( * Github flavored markdown renderer. */ export class MarkdownRenderer { + constructor(protected readonly refDoc: TypeSpecRefDoc) {} headingTitle(item: NamedTypeRefDoc): string { return inlinecode(item.name); } @@ -146,7 +147,11 @@ export class MarkdownRenderer { table([ ["Name", "Type", "Description"], ...[...model.properties.values()].map((prop) => { - return [prop.name, inlinecode(this.ref(prop.type.type)), prop.doc]; + return [ + `${prop.name}${prop.type.optional ? "?" : ""}`, + this.ref(prop.type.type), + prop.doc, + ]; }), ]) ); @@ -154,6 +159,10 @@ export class MarkdownRenderer { } ref(type: Type | ValueType): string { + const namedType = type.kind !== "Value" && this.refDoc.getNamedTypeRefDoc(type); + if (namedType) { + return link(inlinecode(namedType.name), `#${this.anchorId(namedType)}`); + } return "name" in type && typeof type.name === "string" ? inlinecode(type.name) : getTypeSignature(type); @@ -207,14 +216,12 @@ export class MarkdownRenderer { decorator(dec: DecoratorRefDoc) { const content: MarkdownDoc = ["", dec.doc, codeblock(dec.signature, "typespec"), ""]; - content.push( - section("Target", [dec.target.doc, inlinecode(this.ref(dec.target.type.type)), ""]) - ); + content.push(section("Target", [dec.target.doc, this.ref(dec.target.type.type), ""])); if (dec.parameters.length > 0) { const paramTable: string[][] = [["Name", "Type", "Description"]]; for (const param of dec.parameters) { - paramTable.push([param.name, inlinecode(this.ref(param.type.type)), param.doc]); + paramTable.push([param.name, this.ref(param.type.type), param.doc]); } content.push(section("Parameters", [table(paramTable), ""])); } else { diff --git a/packages/tspd/src/ref-doc/extractor.ts b/packages/tspd/src/ref-doc/extractor.ts index 2d2cef3ca1..ff9f2ae1d6 100644 --- a/packages/tspd/src/ref-doc/extractor.ts +++ b/packages/tspd/src/ref-doc/extractor.ts @@ -52,6 +52,7 @@ import { LinterRuleSetRefDoc, ModelPropertyRefDoc, ModelRefDoc, + NamedTypeRefDoc, NamespaceRefDoc, OperationRefDoc, ScalarRefDoc, @@ -65,14 +66,6 @@ import { getQualifier, getTypeSignature } from "./utils/type-signature.js"; * The mutable equivalent of a type. */ -//prettier-ignore -type MutableArrayProps = - T extends ReadonlyMap ? Map : - T extends ReadonlySet ? Set> : - T extends readonly (infer V)[] ? V[] : - // brand to force explicit conversion. - { -readonly [P in keyof T]: MutateIfArray }; - //prettier-ignore type Mutable = T extends ReadonlyMap ? Map : @@ -81,8 +74,6 @@ type Mutable = // brand to force explicit conversion. { -readonly [P in keyof T]: T[P]}; -type MutateIfArray = T extends readonly (infer U)[] ? U[] : T; - export async function extractLibraryRefDocs( libraryPath: string ): Promise<[TypeSpecLibraryRefDoc, readonly Diagnostic[]]> { @@ -93,13 +84,15 @@ export async function extractLibraryRefDocs( description: pkgJson.description, packageJson: pkgJson, namespaces: [], + getNamedTypeRefDoc: (type) => undefined, }; if (pkgJson.tspMain) { const main = resolvePath(libraryPath, pkgJson.tspMain); const program = await compile(NodeHost, main, { parseOptions: { comments: true, docs: true }, }); - refDoc.namespaces = diagnostics.pipe(extractRefDocs(program)).namespaces as any; + const tspEmitter = diagnostics.pipe(extractRefDocs(program)); + Object.assign(refDoc, tspEmitter); for (const diag of program.diagnostics ?? []) { diagnostics.add(diag); } @@ -173,13 +166,11 @@ export function extractRefDocs( ): [TypeSpecRefDocBase, readonly Diagnostic[]] { const diagnostics = createDiagnosticCollector(); const namespaceTypes = diagnostics.pipe(resolveNamespaces(program, options)); - - const refDoc: MutableArrayProps = { - namespaces: [], - }; + const typeMapping = new Map(); + const namespaces: Mutable[] = []; for (const namespace of namespaceTypes) { - const namespaceDoc: MutableArrayProps = { + const namespaceDoc: Mutable = { id: getTypeName(namespace), decorators: [], operations: [], @@ -190,26 +181,39 @@ export function extractRefDocs( scalars: [], }; - refDoc.namespaces.push(namespaceDoc); + namespaces.push(namespaceDoc); + function collectType( + type: Type, + refDoc: T, + array: T[] | readonly T[] + ) { + typeMapping.set(type, refDoc); + (array as any).push(refDoc); + } navigateTypesInNamespace( namespace, { decorator(dec) { - namespaceDoc.decorators.push(extractDecoratorRefDoc(program, dec)); + collectType(dec, extractDecoratorRefDoc(program, dec), namespaceDoc.decorators); }, operation(operation) { if (!isDeclaredType(operation)) { return; } + if (operation.interface === undefined) { - namespaceDoc.operations.push(extractOperationRefDoc(program, operation, undefined)); + collectType( + operation, + extractOperationRefDoc(program, operation, undefined), + namespaceDoc.operations + ); } }, interface(iface) { if (!isDeclaredType(iface)) { return; } - namespaceDoc.interfaces.push(extractInterfaceRefDocs(program, iface)); + collectType(iface, extractInterfaceRefDocs(program, iface), namespaceDoc.interfaces); }, model(model) { if (!isDeclaredType(model)) { @@ -218,32 +222,32 @@ export function extractRefDocs( if (model.name === "") { return; } - namespaceDoc.models.push(extractModelRefDocs(program, model)); + collectType(model, extractModelRefDocs(program, model), namespaceDoc.models); }, enum(e) { if (!isDeclaredType(e)) { return; } - namespaceDoc.enums.push(extractEnumRefDoc(program, e)); + collectType(e, extractEnumRefDoc(program, e), namespaceDoc.enums); }, union(union) { if (!isDeclaredType(union)) { return; } if (union.name !== undefined) { - namespaceDoc.unions.push(extractUnionRefDocs(program, union as any)); + collectType(union, extractUnionRefDocs(program, union as any), namespaceDoc.unions); } }, scalar(scalar) { - namespaceDoc.scalars.push(extractScalarRefDocs(program, scalar as any)); + collectType(scalar, extractScalarRefDocs(program, scalar), namespaceDoc.scalars); }, }, { includeTemplateDeclaration: true, skipSubNamespaces: true } ); } - sort(refDoc.namespaces); - for (const namespace of refDoc.namespaces as MutableArrayProps[]) { + sort(namespaces); + for (const namespace of namespaces) { sort(namespace.decorators); sort(namespace.enums); sort(namespace.interfaces); @@ -253,11 +257,14 @@ export function extractRefDocs( sort(namespace.scalars); } - function sort(arr: { id: string }[]) { - arr.sort((a, b) => a.id.localeCompare(b.id, "en")); + function sort(arr: { id: string }[] | readonly { id: string }[]) { + (arr as { id: string }[]).sort((a, b) => a.id.localeCompare(b.id, "en")); } - return diagnostics.wrap(refDoc); + return diagnostics.wrap({ + namespaces, + getNamedTypeRefDoc: (type) => typeMapping.get(type), + }); } function extractTemplateParameterDocs(program: Program, type: TemplatedType) { diff --git a/packages/tspd/src/ref-doc/types.ts b/packages/tspd/src/ref-doc/types.ts index db61bc68d5..81f630f707 100644 --- a/packages/tspd/src/ref-doc/types.ts +++ b/packages/tspd/src/ref-doc/types.ts @@ -10,6 +10,7 @@ import { NodePackage, Operation, Scalar, + Type, Union, } from "@typespec/compiler"; @@ -39,6 +40,9 @@ export type TypeSpecLibraryRefDoc = TypeSpecRefDocBase & { export type TypeSpecRefDocBase = { readonly namespaces: readonly NamespaceRefDoc[]; + + /** Returns the named type ref doc mapping to that type if is is part of this library. */ + readonly getNamedTypeRefDoc: (type: Type) => NamedTypeRefDoc | undefined; }; export type EmitterRefDoc = { @@ -139,11 +143,6 @@ export type ModelPropertyRefDoc = NamedTypeRefDoc & { readonly type: ModelProperty; }; -export type TypeRefDocRef = { - id: string; - name: string; -}; - export type EnumRefDoc = NamedTypeRefDoc & { readonly type: Enum; }; From 6715c6a0bd19ff86a47317f2f7ec940c77c462d2 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 14:17:11 -0800 Subject: [PATCH 03/24] Show docs --- .../libraries/openapi/reference/data-types.md | 10 +++--- .../libraries/openapi/reference/decorators.md | 6 ++-- .../tspd/src/ref-doc/emitters/docusaurus.ts | 31 +++++++++++++------ .../tspd/src/ref-doc/emitters/markdown.ts | 14 +++++++-- packages/tspd/src/ref-doc/extractor.ts | 25 ++++++++++----- packages/tspd/src/ref-doc/types.ts | 27 ++++++++++++++-- 6 files changed, 81 insertions(+), 32 deletions(-) diff --git a/docs/libraries/openapi/reference/data-types.md b/docs/libraries/openapi/reference/data-types.md index 63480bbba2..32b92bd61c 100644 --- a/docs/libraries/openapi/reference/data-types.md +++ b/docs/libraries/openapi/reference/data-types.md @@ -18,11 +18,11 @@ model TypeSpec.OpenAPI.AdditionalInfo #### Properties -| Name | Type | Description | -| --------------- | -------------------------------------- | -------------------------------------------------------------------------------- | -| termsOfService? | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
| -| contact? | [`Contact`](#TypeSpec.OpenAPI.Contact) | The contact information for the exposed API.
| -| license? | [`License`](#TypeSpec.OpenAPI.License) | The license information for the exposed API.
| +| Name | Type | Description | +| --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- | +| termsOfService? | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
| +| contact? | [`Contact`](./data-types.md#TypeSpec.OpenAPI.Contact) | The contact information for the exposed API.
| +| license? | [`License`](./data-types.md#TypeSpec.OpenAPI.License) | The license information for the exposed API.
| ### `Contact` {#TypeSpec.OpenAPI.Contact} diff --git a/docs/libraries/openapi/reference/decorators.md b/docs/libraries/openapi/reference/decorators.md index 3a999a99fd..5856e93324 100644 --- a/docs/libraries/openapi/reference/decorators.md +++ b/docs/libraries/openapi/reference/decorators.md @@ -110,9 +110,9 @@ The service `title` and `version` are already specified using `@service`. #### Parameters -| Name | Type | Description | -| -------------- | ---------------------------------------------------- | ---------------------- | -| additionalInfo | [`AdditionalInfo`](#TypeSpec.OpenAPI.AdditionalInfo) | Additional information | +| Name | Type | Description | +| -------------- | ------------------------------------------------------------------- | ---------------------- | +| additionalInfo | [`AdditionalInfo`](./data-types.md#TypeSpec.OpenAPI.AdditionalInfo) | Additional information | ### `@operationId` {#@TypeSpec.OpenAPI.operationId} diff --git a/packages/tspd/src/ref-doc/emitters/docusaurus.ts b/packages/tspd/src/ref-doc/emitters/docusaurus.ts index 0dac032a73..7b086ba172 100644 --- a/packages/tspd/src/ref-doc/emitters/docusaurus.ts +++ b/packages/tspd/src/ref-doc/emitters/docusaurus.ts @@ -1,5 +1,6 @@ import { NamedTypeRefDoc, + RefDocEntity, TypeSpecLibraryRefDoc, TypeSpecRefDoc, TypeSpecRefDocBase, @@ -72,25 +73,19 @@ function renderIndexFile(renderer: DocusaurusRenderer, refDoc: TypeSpecLibraryRe const content = []; if (namespace.decorators.length > 0) { - content.push( - section("Decorators", renderer.toc(namespace.decorators, "./decorators.md")) - ); + content.push(section("Decorators", renderer.toc(namespace.decorators))); } if (namespace.interfaces.length > 0) { - content.push( - section("Interfaces", renderer.toc(namespace.interfaces, "./interfaces.md")) - ); + content.push(section("Interfaces", renderer.toc(namespace.interfaces))); } if (namespace.operations.length > 0) { - content.push( - section("Operations", renderer.toc(namespace.operations, "./interfaces.md")) - ); + content.push(section("Operations", renderer.toc(namespace.operations))); } if (namespace.models.length > 0) { - content.push(section("Models", renderer.toc(namespace.models, "./data-types.md"))); + content.push(section("Models", renderer.toc(namespace.models))); } return content; }), @@ -285,6 +280,22 @@ export class DocusaurusRenderer extends MarkdownRenderer { ); } + filename(type: RefDocEntity): string { + switch (type.kind) { + case "decorator": + return "./decorators.md"; + case "operation": + case "interface": + return "./interfaces.md"; + case "model": + case "enum": + case "union": + return "./data-types.md"; + default: + return ""; + } + } + linterRuleLink(url: string) { const homepage = (this.refDoc.packageJson as any).docusaurusWebsite; if (homepage && url.includes(homepage)) { diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index e60f13efc9..cd64b12ae7 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -12,6 +12,7 @@ import { NamedTypeRefDoc, NamespaceRefDoc, OperationRefDoc, + RefDocEntity, ReferencableElement, ScalarRefDoc, TemplateParameterRefDoc, @@ -161,7 +162,10 @@ export class MarkdownRenderer { ref(type: Type | ValueType): string { const namedType = type.kind !== "Value" && this.refDoc.getNamedTypeRefDoc(type); if (namedType) { - return link(inlinecode(namedType.name), `#${this.anchorId(namedType)}`); + return link( + inlinecode(namedType.name), + `${this.filename(namedType)}#${this.anchorId(namedType)}` + ); } return "name" in type && typeof type.name === "string" ? inlinecode(type.name) @@ -267,12 +271,16 @@ export class MarkdownRenderer { }); } - toc(items: readonly ReferencableElement[], filename?: string) { + toc(items: readonly (ReferencableElement & RefDocEntity)[]) { return items.map( - (item) => ` - [${inlinecode(item.name)}](${filename ?? ""}#${this.anchorId(item)})` + (item) => ` - [${inlinecode(item.name)}](${this.filename(item)}#${this.anchorId(item)})` ); } + filename(type: ReferencableElement & RefDocEntity): string { + return ""; + } + install(refDoc: TypeSpecRefDoc) { return section("Install", [codeblock(`npm install ${refDoc.name}`, "bash")]); } diff --git a/packages/tspd/src/ref-doc/extractor.ts b/packages/tspd/src/ref-doc/extractor.ts index ff9f2ae1d6..5c1fbe8af1 100644 --- a/packages/tspd/src/ref-doc/extractor.ts +++ b/packages/tspd/src/ref-doc/extractor.ts @@ -52,9 +52,9 @@ import { LinterRuleSetRefDoc, ModelPropertyRefDoc, ModelRefDoc, - NamedTypeRefDoc, NamespaceRefDoc, OperationRefDoc, + RefDocEntity, ScalarRefDoc, TypeSpecLibraryRefDoc, TypeSpecRefDocBase, @@ -166,12 +166,15 @@ export function extractRefDocs( ): [TypeSpecRefDocBase, readonly Diagnostic[]] { const diagnostics = createDiagnosticCollector(); const namespaceTypes = diagnostics.pipe(resolveNamespaces(program, options)); - const typeMapping = new Map(); + const typeMapping = new Map(); const namespaces: Mutable[] = []; for (const namespace of namespaceTypes) { + const name = getTypeName(namespace); const namespaceDoc: Mutable = { - id: getTypeName(namespace), + kind: "namespace", + id: name, + name, decorators: [], operations: [], interfaces: [], @@ -182,11 +185,7 @@ export function extractRefDocs( }; namespaces.push(namespaceDoc); - function collectType( - type: Type, - refDoc: T, - array: T[] | readonly T[] - ) { + function collectType(type: Type, refDoc: T, array: T[] | readonly T[]) { typeMapping.set(type, refDoc); (array as any).push(refDoc); } @@ -301,6 +300,7 @@ function extractInterfaceRefDocs(program: Program, iface: Interface): InterfaceR }); } return { + kind: "interface", id: getNamedTypeId(iface), name: iface.name, signature: getTypeSignature(iface), @@ -338,6 +338,7 @@ function extractOperationRefDoc( } } return { + kind: "operation", id: getNamedTypeId(operation), name: interfaceName ? `${interfaceName}.${operation.name}` : operation.name, signature: getTypeSignature(operation), @@ -361,6 +362,7 @@ function extractDecoratorRefDoc(program: Program, decorator: Decorator): Decorat }); } return { + kind: "decorator", type: x, doc: paramDoc.get(x.name) ?? "", name: x.name, @@ -380,6 +382,7 @@ function extractDecoratorRefDoc(program: Program, decorator: Decorator): Decorat }); } return { + kind: "decorator", id: getNamedTypeId(decorator), name: decorator.name, type: decorator, @@ -409,6 +412,7 @@ function extractModelRefDocs(program: Program, type: Model): ModelRefDoc { }); } return { + kind: "model", id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), @@ -445,6 +449,7 @@ function extractEnumRefDoc(program: Program, type: Enum): EnumRefDoc { }); } return { + kind: "enum", id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), @@ -464,6 +469,7 @@ function extractUnionRefDocs(program: Program, type: Union & { name: string }): }); } return { + kind: "union", id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), @@ -485,6 +491,7 @@ function extractScalarRefDocs(program: Program, type: Scalar): ScalarRefDoc { }); } return { + kind: "scalar", id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), @@ -628,6 +635,7 @@ function extractLinterRuleSetsRefDoc( return Object.entries(ruleSets).map(([name, ruleSet]) => { const fullName = `${libName}/${name}`; return { + kind: "ruleset", id: fullName, name: fullName, ruleSet, @@ -640,6 +648,7 @@ function extractLinterRuleRefDoc( ): LinterRuleRefDoc { const fullName = `${libName}/${rule.name}`; return { + kind: "rule", id: fullName, name: fullName, rule, diff --git a/packages/tspd/src/ref-doc/types.ts b/packages/tspd/src/ref-doc/types.ts index 81f630f707..e39fe0b2ee 100644 --- a/packages/tspd/src/ref-doc/types.ts +++ b/packages/tspd/src/ref-doc/types.ts @@ -42,7 +42,7 @@ export type TypeSpecRefDocBase = { readonly namespaces: readonly NamespaceRefDoc[]; /** Returns the named type ref doc mapping to that type if is is part of this library. */ - readonly getNamedTypeRefDoc: (type: Type) => NamedTypeRefDoc | undefined; + readonly getNamedTypeRefDoc: (type: Type) => RefDocEntity | undefined; }; export type EmitterRefDoc = { @@ -56,9 +56,11 @@ export type LinterRefDoc = { }; export type LinterRuleSetRefDoc = ReferencableElement & { + readonly kind: "ruleset"; readonly ruleSet: LinterRuleSet; }; export type LinterRuleRefDoc = ReferencableElement & { + readonly kind: "rule"; readonly rule: LinterRuleDefinition; }; @@ -68,8 +70,22 @@ export type EmitterOptionRefDoc = { readonly doc: string; }; +export type RefDocEntity = + | NamespaceRefDoc + | DecoratorRefDoc + | OperationRefDoc + | InterfaceRefDoc + | ModelRefDoc + | EnumRefDoc + | UnionRefDoc + | ScalarRefDoc + | LinterRuleSetRefDoc + | LinterRuleRefDoc; + export type NamespaceRefDoc = { + readonly kind: "namespace"; readonly id: string; + readonly name: string; readonly decorators: readonly DecoratorRefDoc[]; readonly operations: readonly OperationRefDoc[]; readonly interfaces: readonly InterfaceRefDoc[]; @@ -95,6 +111,7 @@ export type NamedTypeRefDoc = ReferencableElement & { }; export type DecoratorRefDoc = NamedTypeRefDoc & { + readonly kind: "decorator"; readonly type: Decorator; readonly target: FunctionParameterRefDoc; readonly parameters: readonly FunctionParameterRefDoc[]; @@ -115,15 +132,15 @@ export type ExampleRefDoc = { }; export type OperationRefDoc = NamedTypeRefDoc & { + readonly kind: "operation"; readonly type: Operation; - readonly templateParameters?: TemplateParameterRefDoc[]; }; export type InterfaceRefDoc = NamedTypeRefDoc & { + readonly kind: "interface"; readonly type: Interface; readonly templateParameters?: readonly TemplateParameterRefDoc[]; - readonly interfaceOperations: readonly OperationRefDoc[]; }; @@ -133,6 +150,7 @@ export type TemplateParameterRefDoc = { }; export type ModelRefDoc = NamedTypeRefDoc & { + readonly kind: "model"; readonly type: Model; readonly templateParameters?: readonly TemplateParameterRefDoc[]; @@ -144,16 +162,19 @@ export type ModelPropertyRefDoc = NamedTypeRefDoc & { }; export type EnumRefDoc = NamedTypeRefDoc & { + readonly kind: "enum"; readonly type: Enum; }; export type UnionRefDoc = NamedTypeRefDoc & { + readonly kind: "union"; readonly type: Union; readonly templateParameters?: readonly TemplateParameterRefDoc[]; }; export type ScalarRefDoc = NamedTypeRefDoc & { + readonly kind: "scalar"; readonly type: Scalar; readonly templateParameters?: readonly TemplateParameterRefDoc[]; From a2301a70137afaf3ddcf82e5763c8f5cd796e50a Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 14:25:52 -0800 Subject: [PATCH 04/24] Regen docs --- docs/libraries/http/reference/data-types.md | 177 ++++++++++++++++++ docs/libraries/http/reference/decorators.md | 12 +- .../json-schema/reference/data-types.md | 6 + .../json-schema/reference/decorators.md | 26 +-- .../libraries/openapi/reference/decorators.md | 22 +-- .../protobuf/reference/data-types.md | 42 +++++ .../protobuf/reference/decorators.md | 16 +- docs/libraries/rest/reference/data-types.md | 57 ++++++ .../versioning/reference/decorators.md | 22 +-- docs/standard-library/built-in-data-types.md | 29 +++ docs/standard-library/built-in-decorators.md | 22 +-- packages/http/README.md | 12 +- packages/json-schema/README.md | 26 +-- packages/openapi/README.md | 22 +-- packages/protobuf/README.md | 16 +- .../tspd/src/ref-doc/emitters/markdown.ts | 6 +- packages/versioning/README.md | 22 +-- .../website/.scripts/regen-compiler-docs.mjs | 2 +- 18 files changed, 424 insertions(+), 113 deletions(-) diff --git a/docs/libraries/http/reference/data-types.md b/docs/libraries/http/reference/data-types.md index ef32d587f6..05232ad9b7 100644 --- a/docs/libraries/http/reference/data-types.md +++ b/docs/libraries/http/reference/data-types.md @@ -16,6 +16,12 @@ The request has been accepted for processing, but processing has not yet complet model TypeSpec.Http.AcceptedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 202` | The status code. | + ### `ApiKeyAuth` {#TypeSpec.Http.ApiKeyAuth} An API key is a token that a client provides when making API calls. The key can be sent in the query string: @@ -49,6 +55,14 @@ model TypeSpec.Http.ApiKeyAuth | Location | The location of the API key | | Name | The name of the API key | +#### Properties + +| Name | Type | Description | +| ---- | ---------- | ----------- | +| type | `apiKey` | | +| in | `Location` | | +| name | `Name` | | + ### `AuthorizationCodeFlow` {#TypeSpec.Http.AuthorizationCodeFlow} Authorization Code flow @@ -57,6 +71,16 @@ Authorization Code flow model TypeSpec.Http.AuthorizationCodeFlow ``` +#### Properties + +| Name | Type | Description | +| ---------------- | ------------------- | --------------------------------- | +| type | `authorizationCode` | authorization code flow | +| authorizationUrl | `string` | the authorization URL | +| tokenUrl | `string` | the token URL | +| refreshUrl? | `string` | the refresh URL | +| scopes | `Array` | list of scopes for the credential | + ### `BadRequestResponse` {#TypeSpec.Http.BadRequestResponse} The server could not understand the request due to invalid syntax. @@ -65,6 +89,12 @@ The server could not understand the request due to invalid syntax. model TypeSpec.Http.BadRequestResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 400` | The status code. | + ### `BasicAuth` {#TypeSpec.Http.BasicAuth} Basic authentication is a simple authentication scheme built into the HTTP protocol. @@ -79,6 +109,13 @@ Authorization: Basic ZGVtbzpwQDU1dzByZA== model TypeSpec.Http.BasicAuth ``` +#### Properties + +| Name | Type | Description | +| ------ | ------------------ | ------------------- | +| type | `http` | Http authentication | +| scheme | `(string) "basic"` | basic auth scheme | + ### `BearerAuth` {#TypeSpec.Http.BearerAuth} Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. @@ -93,6 +130,13 @@ Authorization: Bearer model TypeSpec.Http.BearerAuth ``` +#### Properties + +| Name | Type | Description | +| ------ | ------------------- | ------------------- | +| type | `http` | Http authentication | +| scheme | `(string) "bearer"` | bearer auth scheme | + ### `Body` {#TypeSpec.Http.Body} Defines a model with a single property of the given type, marked with `@body`. @@ -110,6 +154,12 @@ model TypeSpec.Http.Body | ---- | ---------------------------------------- | | Type | The type of the model's `body` property. | +#### Properties + +| Name | Type | Description | +| ---- | ------ | ----------- | +| body | `Type` | | + ### `ClientCredentialsFlow` {#TypeSpec.Http.ClientCredentialsFlow} Client credentials flow @@ -118,6 +168,15 @@ Client credentials flow model TypeSpec.Http.ClientCredentialsFlow ``` +#### Properties + +| Name | Type | Description | +| ----------- | ------------------- | --------------------------------- | +| type | `clientCredentials` | client credential flow | +| tokenUrl | `string` | the token URL | +| refreshUrl? | `string` | the refresh URL | +| scopes | `Array` | list of scopes for the credential | + ### `ConflictResponse` {#TypeSpec.Http.ConflictResponse} The request conflicts with the current state of the server. @@ -126,6 +185,12 @@ The request conflicts with the current state of the server. model TypeSpec.Http.ConflictResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 409` | The status code. | + ### `CreatedResponse` {#TypeSpec.Http.CreatedResponse} The request has succeeded and a new resource has been created as a result. @@ -134,6 +199,12 @@ The request has succeeded and a new resource has been created as a result. model TypeSpec.Http.CreatedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 201` | The status code. | + ### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse} Access is forbidden. @@ -142,6 +213,12 @@ Access is forbidden. model TypeSpec.Http.ForbiddenResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 403` | The status code. | + ### `HeaderOptions` {#TypeSpec.Http.HeaderOptions} Header options. @@ -150,6 +227,13 @@ Header options. model TypeSpec.Http.HeaderOptions ``` +#### Properties + +| Name | Type | Description | +| ------- | ------------------------------------------------------------- | --------------------------------------------------------------- | +| name? | `string` | Name of the header when sent over HTTP.
| +| format? | `union csv \| multi \| tsv \| ssv \| pipes \| simple \| form` | Determines the format of the array if type array is used.
| + ### `ImplicitFlow` {#TypeSpec.Http.ImplicitFlow} Implicit flow @@ -158,6 +242,15 @@ Implicit flow model TypeSpec.Http.ImplicitFlow ``` +#### Properties + +| Name | Type | Description | +| ---------------- | ---------- | --------------------------------- | +| type | `implicit` | implicit flow | +| authorizationUrl | `string` | the authorization URL | +| refreshUrl? | `string` | the refresh URL | +| scopes | `Array` | list of scopes for the credential | + ### `LocationHeader` {#TypeSpec.Http.LocationHeader} The Location header contains the URL where the status of the long running operation can be checked. @@ -166,6 +259,12 @@ The Location header contains the URL where the status of the long running operat model TypeSpec.Http.LocationHeader ``` +#### Properties + +| Name | Type | Description | +| -------- | -------- | --------------------------------------------------------------------------------------------------- | +| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. | + ### `MovedResponse` {#TypeSpec.Http.MovedResponse} The URL of the requested resource has been changed permanently. The new URL is given in the response. @@ -174,6 +273,13 @@ The URL of the requested resource has been changed permanently. The new URL is g model TypeSpec.Http.MovedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | --------------------------------------------------------------------------------------------------- | +| statusCode | `(number) 301` | The status code. | +| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. | + ### `NoContentResponse` {#TypeSpec.Http.NoContentResponse} There is no content to send for this request, but the headers may be useful. @@ -182,6 +288,12 @@ There is no content to send for this request, but the headers may be useful. model TypeSpec.Http.NoContentResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 204` | The status code. | + ### `NotFoundResponse` {#TypeSpec.Http.NotFoundResponse} The server cannot find the requested resource. @@ -190,6 +302,12 @@ The server cannot find the requested resource. model TypeSpec.Http.NotFoundResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 404` | The status code. | + ### `NotModifiedResponse` {#TypeSpec.Http.NotModifiedResponse} The client has made a conditional request and the resource has not been modified. @@ -198,6 +316,12 @@ The client has made a conditional request and the resource has not been modified model TypeSpec.Http.NotModifiedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 304` | The status code. | + ### `OAuth2Auth` {#TypeSpec.Http.OAuth2Auth} OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server. @@ -216,6 +340,13 @@ model TypeSpec.Http.OAuth2Auth | ----- | ---------------------------------- | | Flows | The list of supported OAuth2 flows | +#### Properties + +| Name | Type | Description | +| ----- | -------- | ----------- | +| type | `oauth2` | | +| flows | `Flows` | | + ### `OkResponse` {#TypeSpec.Http.OkResponse} The request has succeeded. @@ -224,6 +355,12 @@ The request has succeeded. model TypeSpec.Http.OkResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 200` | The status code. | + ### `OpenIdConnectAuth` {#TypeSpec.Http.OpenIdConnectAuth} OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol and supported by some OAuth 2.0 providers, such as Google and Azure Active Directory. @@ -245,6 +382,13 @@ model TypeSpec.Http.OpenIdConnectAuth | ---------- | ----------- | | ConnectUrl | | +#### Properties + +| Name | Type | Description | +| ---------------- | --------------- | ----------------------------------------------------------------- | +| type | `openIdConnect` | Auth type
| +| openIdConnectUrl | `ConnectUrl` | Connect url. It can be specified relative to the server URL
| + ### `PasswordFlow` {#TypeSpec.Http.PasswordFlow} Resource Owner Password flow @@ -253,6 +397,15 @@ Resource Owner Password flow model TypeSpec.Http.PasswordFlow ``` +#### Properties + +| Name | Type | Description | +| ---------------- | ---------- | --------------------------------- | +| type | `password` | password flow | +| authorizationUrl | `string` | the authorization URL | +| refreshUrl? | `string` | the refresh URL | +| scopes | `Array` | list of scopes for the credential | + ### `PlainData` {#TypeSpec.Http.PlainData} Produces a new model with the same properties as T, but with `@query`, @@ -268,6 +421,11 @@ model TypeSpec.Http.PlainData | ---- | -------------------------------------- | | Data | The model to spread as the plain data. | +#### Properties + +| Name | Type | Description | +| ---- | ---- | ----------- | + ### `QueryOptions` {#TypeSpec.Http.QueryOptions} Query parameter options. @@ -276,6 +434,13 @@ Query parameter options. model TypeSpec.Http.QueryOptions ``` +#### Properties + +| Name | Type | Description | +| ------- | ------------------------------------------------------------- | --------------------------------------------------------------- | +| name? | `string` | Name of the query when included in the url.
| +| format? | `union multi \| csv \| ssv \| tsv \| simple \| form \| pipes` | Determines the format of the array if type array is used.
| + ### `Response` {#TypeSpec.Http.Response} Describes an HTTP response. @@ -290,6 +455,12 @@ model TypeSpec.Http.Response | ------ | -------------------------------- | | Status | The status code of the response. | +#### Properties + +| Name | Type | Description | +| ---------- | -------- | ----------- | +| statusCode | `Status` | | + ### `UnauthorizedResponse` {#TypeSpec.Http.UnauthorizedResponse} Access is unauthorized. @@ -298,6 +469,12 @@ Access is unauthorized. model TypeSpec.Http.UnauthorizedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 401` | The status code. | + ### `ApiKeyLocation` {#TypeSpec.Http.ApiKeyLocation} Describes the location of the API key diff --git a/docs/libraries/http/reference/decorators.md b/docs/libraries/http/reference/decorators.md index 29d75b1c02..6b095e67b3 100644 --- a/docs/libraries/http/reference/decorators.md +++ b/docs/libraries/http/reference/decorators.md @@ -151,7 +151,7 @@ Specify if inapplicable metadata should be included in the payload for the given #### Target -`(intrinsic) unknown` +`unknown` #### Parameters @@ -301,10 +301,10 @@ it will be used as a prefix to the route URI of the operation. #### Parameters -| Name | Type | Description | -| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| path | `valueof scalar string` | Relative route path. Cannot include query parameters. | -| options | `model (anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| Name | Type | Description | +| ------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `valueof scalar string` | Relative route path. Cannot include query parameters. | +| options | `` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | #### Examples @@ -331,7 +331,7 @@ Specify the endpoint for this service. | ----------- | ----------------------- | ------------------------------------------------------- | | url | `valueof scalar string` | Server endpoint | | description | `valueof scalar string` | Description of the endpoint | -| parameters | `model Record` | Optional set of parameters used to interpolate the url. | +| parameters | `Record` | Optional set of parameters used to interpolate the url. | #### Examples diff --git a/docs/libraries/json-schema/reference/data-types.md b/docs/libraries/json-schema/reference/data-types.md index 385b1d1a99..845b3e54b8 100644 --- a/docs/libraries/json-schema/reference/data-types.md +++ b/docs/libraries/json-schema/reference/data-types.md @@ -23,6 +23,12 @@ model TypeSpec.JsonSchema.Json | ---- | ------------------------------- | | Data | the type to convert to raw JSON | +#### Properties + +| Name | Type | Description | +| ----- | ------ | ----------- | +| value | `Data` | | + ### `Format` {#TypeSpec.JsonSchema.Format} Well-known JSON Schema formats. diff --git a/docs/libraries/json-schema/reference/decorators.md b/docs/libraries/json-schema/reference/decorators.md index cf75aea96c..39d7069aa0 100644 --- a/docs/libraries/json-schema/reference/decorators.md +++ b/docs/libraries/json-schema/reference/decorators.md @@ -41,9 +41,9 @@ Use `@minContains` and `@maxContains` to customize how many instances to expect. #### Parameters -| Name | Type | Description | -| ----- | --------------------- | -------------------------------- | -| value | `(intrinsic) unknown` | The type the array must contain. | +| Name | Type | Description | +| ----- | --------- | -------------------------------- | +| value | `unknown` | The type the array must contain. | ### `@contentEncoding` {#@TypeSpec.JsonSchema.contentEncoding} @@ -96,9 +96,9 @@ media type and encoding. #### Parameters -| Name | Type | Description | -| ----- | --------------------- | --------------------------------- | -| value | `(intrinsic) unknown` | the schema of the string contents | +| Name | Type | Description | +| ----- | --------- | --------------------------------- | +| value | `unknown` | the schema of the string contents | ### `@extension` {#@TypeSpec.JsonSchema.extension} @@ -114,14 +114,14 @@ emit the raw JSON code `{x: "value"}`. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | | ----- | ----------------------- | --------------------------------------------------------------------------------------- | | key | `valueof scalar string` | the name of the keyword of vendor extension, e.g. `x-custom`. | -| value | `(intrinsic) unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | +| value | `unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | ### `@id` {#@TypeSpec.JsonSchema.id} @@ -136,7 +136,7 @@ By default, the id will be constructed based on the declaration's name. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters @@ -158,7 +158,7 @@ you can provide the id. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters @@ -272,9 +272,9 @@ Specify that the target array must begin with the provided types. #### Parameters -| Name | Type | Description | -| ----- | ----------------- | --------------------------------------------------------------------------- | -| value | `model unknown[]` | a tuple containing the types that must be present at the start of the array | +| Name | Type | Description | +| ----- | ------- | --------------------------------------------------------------------------- | +| value | `Array` | a tuple containing the types that must be present at the start of the array | ### `@uniqueItems` {#@TypeSpec.JsonSchema.uniqueItems} diff --git a/docs/libraries/openapi/reference/decorators.md b/docs/libraries/openapi/reference/decorators.md index 5856e93324..47fbb964c1 100644 --- a/docs/libraries/openapi/reference/decorators.md +++ b/docs/libraries/openapi/reference/decorators.md @@ -48,10 +48,10 @@ Attach some custom data to the OpenAPI element generated from this type. #### Parameters -| Name | Type | Description | -| ----- | --------------------- | ----------------------------------- | -| key | valueof scalar string | Extension key. Must start with `x-` | -| value | `unknown` | Extension value. | +| Name | Type | Description | +| ----- | ----------------------- | ----------------------------------- | +| key | `valueof scalar string` | Extension key. Must start with `x-` | +| value | `unknown` | Extension value. | #### Examples @@ -80,10 +80,10 @@ Specify the OpenAPI `externalDocs` property for this type. #### Parameters -| Name | Type | Description | -| ----------- | --------------------- | ----------------------- | -| url | valueof scalar string | Url to the docs | -| description | valueof scalar string | Description of the docs | +| Name | Type | Description | +| ----------- | ----------------------- | ----------------------- | +| url | `valueof scalar string` | Url to the docs | +| description | `valueof scalar string` | Description of the docs | #### Examples @@ -128,9 +128,9 @@ Specify the OpenAPI `operationId` property for this operation. #### Parameters -| Name | Type | Description | -| ----------- | --------------------- | ------------------- | -| operationId | valueof scalar string | Operation id value. | +| Name | Type | Description | +| ----------- | ----------------------- | ------------------- | +| operationId | `valueof scalar string` | Operation id value. | #### Examples diff --git a/docs/libraries/protobuf/reference/data-types.md b/docs/libraries/protobuf/reference/data-types.md index 3c12f0f9f7..603427920e 100644 --- a/docs/libraries/protobuf/reference/data-types.md +++ b/docs/libraries/protobuf/reference/data-types.md @@ -40,6 +40,12 @@ model TypeSpec.Protobuf.Extern model Widget is Extern<"path/to/test.proto", "test.Widget">; ``` +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | + ### `Map` {#TypeSpec.Protobuf.Map} A type representing a Protobuf `map`. Instances of this type in models will be converted to the built-in `map` type @@ -59,6 +65,11 @@ model TypeSpec.Protobuf.Map | Key | the key type (any integral type or string) | | Value | the value type (any type other than another map) | +#### Properties + +| Name | Type | Description | +| ---- | ---- | ----------- | + ### `PackageDetails` {#TypeSpec.Protobuf.PackageDetails} Details applied to a package definition by the [`@package`](./decorators# @@ -67,6 +78,13 @@ Details applied to a package definition by the [`@package`](./decorators# model TypeSpec.Protobuf.PackageDetails ``` +#### Properties + +| Name | Type | Description | +| -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name? | `string` | The package's name.

By default, the package's name is constructed from the namespace it is applied to.
| +| options? | `Record` | The package's top-level options.

See the [Protobuf Language Guide - Options](https://protobuf.dev/programming-guides/proto3/#options) for more information.

Currently, only string, boolean, and numeric options are supported.
| + ### `StreamMode` {#TypeSpec.Protobuf.StreamMode} The streaming mode of an operation. One of: @@ -166,6 +184,12 @@ This model references `google.protobuf.Any` from `google/protobuf/any.proto`. model TypeSpec.Protobuf.WellKnown.Any ``` +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | + ### `Empty` {#TypeSpec.Protobuf.WellKnown.Empty} An empty message. @@ -176,6 +200,12 @@ This model references `google.protobuf.Empty` from `google/protobuf/empty.proto` model TypeSpec.Protobuf.WellKnown.Empty ``` +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | + ### `LatLng` {#TypeSpec.Protobuf.WellKnown.LatLng} A latitude and longitude. @@ -186,6 +216,12 @@ This model references `google.type.LatLng` from `google/type/latlng.proto`. model TypeSpec.Protobuf.WellKnown.LatLng ``` +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | + ### `Timestamp` {#TypeSpec.Protobuf.WellKnown.Timestamp} A timestamp. @@ -195,3 +231,9 @@ This model references `google.protobuf.Timestamp` from `google/protobuf/timestam ```typespec model TypeSpec.Protobuf.WellKnown.Timestamp ``` + +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | diff --git a/docs/libraries/protobuf/reference/decorators.md b/docs/libraries/protobuf/reference/decorators.md index 7ec642c0fe..3a16ef5385 100644 --- a/docs/libraries/protobuf/reference/decorators.md +++ b/docs/libraries/protobuf/reference/decorators.md @@ -59,7 +59,7 @@ This decorator will force the emitter to check and emit a model. #### Target -`model {}` +`` #### Parameters @@ -80,9 +80,9 @@ single Protobuf file. #### Parameters -| Name | Type | Description | -| ------- | ---------------------------------------- | ----------------------------------- | -| details | `model TypeSpec.Protobuf.PackageDetails` | the optional details of the package | +| Name | Type | Description | +| ------- | -------------------------------------------------------------------- | ----------------------------------- | +| details | [`PackageDetails`](./data-types.md#TypeSpec.Protobuf.PackageDetails) | the optional details of the package | ### `@reserve` {#@TypeSpec.Protobuf.reserve} @@ -113,7 +113,7 @@ information. #### Target -`model {}` +`` #### Parameters @@ -162,9 +162,9 @@ Set the streaming mode of an operation. See [StreamMode](./data-types#TypeSpec.P #### Parameters -| Name | Type | Description | -| ---- | ----------------------------------- | ---------------------------------------------- | -| mode | `enum TypeSpec.Protobuf.StreamMode` | The streaming mode to apply to this operation. | +| Name | Type | Description | +| ---- | ------------------------------------------------------------ | ---------------------------------------------- | +| mode | [`StreamMode`](./data-types.md#TypeSpec.Protobuf.StreamMode) | The streaming mode to apply to this operation. | #### Examples diff --git a/docs/libraries/rest/reference/data-types.md b/docs/libraries/rest/reference/data-types.md index b179018191..7f03e5d814 100644 --- a/docs/libraries/rest/reference/data-types.md +++ b/docs/libraries/rest/reference/data-types.md @@ -35,6 +35,13 @@ model TypeSpec.Rest.Resource.CollectionWithNextLink | -------- | ------------------------------------ | | Resource | The resource type of the collection. | +#### Properties + +| Name | Type | Description | +| --------- | ------------------ | ----------- | +| value | `Array` | | +| nextLink? | `ResourceLocation` | | + ### `KeysOf` {#TypeSpec.Rest.Resource.KeysOf} Dynamically gathers keys of the model type `Resource`. @@ -49,6 +56,11 @@ model TypeSpec.Rest.Resource.KeysOf | -------- | -------------------------- | | Resource | The target resource model. | +#### Properties + +| Name | Type | Description | +| ---- | ---- | ----------- | + ### `ParentKeysOf` {#TypeSpec.Rest.Resource.ParentKeysOf} Dynamically gathers parent keys of the model type `Resource`. @@ -63,6 +75,11 @@ model TypeSpec.Rest.Resource.ParentKeysOf | -------- | -------------------------- | | Resource | The target resource model. | +#### Properties + +| Name | Type | Description | +| ---- | ---- | ----------- | + ### `ResourceCollectionParameters` {#TypeSpec.Rest.Resource.ResourceCollectionParameters} Represents collection operation parameters for the resource of type `Resource`. @@ -77,6 +94,11 @@ model TypeSpec.Rest.Resource.ResourceCollectionParameters | -------- | ------------------- | | Resource | The resource model. | +#### Properties + +| Name | Type | Description | +| ---- | ---- | ----------- | + ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} Resource create operation completed successfully. @@ -91,6 +113,13 @@ model TypeSpec.Rest.Resource.ResourceCreatedResponse | -------- | ------------------------------------ | | Resource | The resource model that was created. | +#### Properties + +| Name | Type | Description | +| ---------- | -------------- | ---------------- | +| statusCode | `(number) 201` | The status code. | +| body | `Resource` | | + ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} Resource create operation model. @@ -105,6 +134,11 @@ model TypeSpec.Rest.Resource.ResourceCreateModel | -------- | ----------------------------- | | Resource | The resource model to create. | +#### Properties + +| Name | Type | Description | +| ---- | ---- | ----------- | + ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} Resource create or update operation model. @@ -119,6 +153,11 @@ model TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel | -------- | --------------------------------------- | | Resource | The resource model to create or update. | +#### Properties + +| Name | Type | Description | +| ---- | ---- | ----------- | + ### `ResourceDeletedResponse` {#TypeSpec.Rest.Resource.ResourceDeletedResponse} Resource deleted successfully. @@ -127,6 +166,12 @@ Resource deleted successfully. model TypeSpec.Rest.Resource.ResourceDeletedResponse ``` +#### Properties + +| Name | Type | Description | +| ---- | -------------- | ---------------- | +| \_ | `(number) 200` | The status code. | + ### `ResourceError` {#TypeSpec.Rest.Resource.ResourceError} The default error response for resource operations. @@ -135,6 +180,13 @@ The default error response for resource operations. model TypeSpec.Rest.Resource.ResourceError ``` +#### Properties + +| Name | Type | Description | +| ------- | -------- | ------------------ | +| code | `int32` | The error code. | +| message | `string` | The error message. | + ### `ResourceParameters` {#TypeSpec.Rest.Resource.ResourceParameters} Represents operation parameters for the resource of type `Resource`. @@ -148,3 +200,8 @@ model TypeSpec.Rest.Resource.ResourceParameters | Name | Description | | -------- | ------------------- | | Resource | The resource model. | + +#### Properties + +| Name | Type | Description | +| ---- | ---- | ----------- | diff --git a/docs/libraries/versioning/reference/decorators.md b/docs/libraries/versioning/reference/decorators.md index 1f752c8b5a..871efc731e 100644 --- a/docs/libraries/versioning/reference/decorators.md +++ b/docs/libraries/versioning/reference/decorators.md @@ -147,10 +147,10 @@ Identifies when the target type changed. #### Parameters -| Name | Type | Description | -| ------- | --------------------- | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `(intrinsic) unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | -------------------------------------------- | +| version | `EnumMember` | The version that the target type changed in. | +| oldType | `unknown` | The previous type of the target. | ### `@typeChangedFrom` {#@TypeSpec.Versioning.typeChangedFrom} @@ -166,10 +166,10 @@ Identifies when the target type changed. #### Parameters -| Name | Type | Description | -| ------- | --------------------- | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `(intrinsic) unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | -------------------------------------------- | +| version | `EnumMember` | The version that the target type changed in. | +| oldType | `unknown` | The previous type of the target. | ### `@useDependency` {#@TypeSpec.Versioning.useDependency} @@ -185,9 +185,9 @@ Identifies that a namespace or a given versioning enum member relies upon a vers #### Parameters -| Name | Type | Description | -| -------------- | -------------------- | --------------------------------------------------------------------- | -| versionRecords | `model EnumMember[]` | The dependent library version(s) for the target namespace or version. | +| Name | Type | Description | +| -------------- | ------- | --------------------------------------------------------------------- | +| versionRecords | `Array` | The dependent library version(s) for the target namespace or version. | #### Examples diff --git a/docs/standard-library/built-in-data-types.md b/docs/standard-library/built-in-data-types.md index c4971cec36..0bc4fc5ac2 100644 --- a/docs/standard-library/built-in-data-types.md +++ b/docs/standard-library/built-in-data-types.md @@ -20,6 +20,9 @@ model Array | Element | The type of the array elements | +#### Properties +| Name | Type | Description | +|------|------|-------------| ### `DefaultKeyVisibility` {#DefaultKeyVisibility} @@ -36,6 +39,9 @@ model DefaultKeyVisibility | Visibility | The visibility to apply to all properties. | +#### Properties +| Name | Type | Description | +|------|------|-------------| ### `object` {#object} @@ -46,6 +52,9 @@ model object ``` +#### Properties +| Name | Type | Description | +|------|------|-------------| ### `OmitDefaults` {#OmitDefaults} @@ -61,6 +70,9 @@ model OmitDefaults | Source | An object whose spread property defaults are all omitted. | +#### Properties +| Name | Type | Description | +|------|------|-------------| ### `OmitProperties` {#OmitProperties} @@ -77,6 +89,9 @@ model OmitProperties | Keys | The property keys to omit. | +#### Properties +| Name | Type | Description | +|------|------|-------------| ### `OptionalProperties` {#OptionalProperties} @@ -92,6 +107,9 @@ model OptionalProperties | Source | An object whose spread properties are all optional. | +#### Properties +| Name | Type | Description | +|------|------|-------------| ### `Record` {#Record} @@ -108,6 +126,9 @@ model Record | Element | The type of the properties | +#### Properties +| Name | Type | Description | +|------|------|-------------| ### `ServiceOptions` {#ServiceOptions} @@ -118,6 +139,11 @@ model ServiceOptions ``` +#### Properties +| Name | Type | Description | +|------|------|-------------| +| title? | [`string`](#string) | Title of the service.
| +| version? | [`string`](#string) | Version of the service.
| ### `UpdateableProperties` {#UpdateableProperties} @@ -133,6 +159,9 @@ model UpdateableProperties | Source | An object whose spread properties are all updateable. | +#### Properties +| Name | Type | Description | +|------|------|-------------| ### `BytesKnownEncoding` {#BytesKnownEncoding} diff --git a/docs/standard-library/built-in-decorators.md b/docs/standard-library/built-in-decorators.md index 58abd9aea7..e50c1d5bd6 100644 --- a/docs/standard-library/built-in-decorators.md +++ b/docs/standard-library/built-in-decorators.md @@ -17,7 +17,7 @@ NOTE: This decorator **should not** be used, use the `#deprecated` directive ins #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | @@ -80,13 +80,13 @@ Attach a documentation string. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| | doc | `valueof scalar string` | Documentation string | -| formatArgs | `model {}` | Record with key value pair that can be interpolated in the doc. | +| formatArgs | `` | Record with key value pair that can be interpolated in the doc. | #### Examples @@ -142,7 +142,7 @@ Provide an alternative name for this type when serialized to the given mime type #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | @@ -258,13 +258,13 @@ Specifies how a templated type should name their instances. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| | name | `valueof scalar string` | name the template instance should take | -| formatArgs | `(intrinsic) unknown` | Model with key value used to interpolate the name | +| formatArgs | `unknown` | Model with key value used to interpolate the name | #### Examples @@ -287,7 +287,7 @@ A debugging decorator used to inspect a type. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | @@ -306,7 +306,7 @@ A debugging decorator used to inspect a type name. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | @@ -684,7 +684,7 @@ Provide an alternative name for this type. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | @@ -785,7 +785,7 @@ Mark this namespace as describing a service and configure service properties. #### Parameters | Name | Type | Description | |------|------|-------------| -| options | `model ServiceOptions` | Optional configuration for the service. | +| options | [`ServiceOptions`](./data-types.md#ServiceOptions) | Optional configuration for the service. | #### Examples @@ -819,7 +819,7 @@ Typically a short, single-line description. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | diff --git a/packages/http/README.md b/packages/http/README.md index b35b6e2ea3..4c028f6b17 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -196,7 +196,7 @@ Specify if inapplicable metadata should be included in the payload for the given ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters @@ -346,10 +346,10 @@ it will be used as a prefix to the route URI of the operation. ##### Parameters -| Name | Type | Description | -| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| path | `valueof scalar string` | Relative route path. Cannot include query parameters. | -| options | `model (anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| Name | Type | Description | +| ------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `valueof scalar string` | Relative route path. Cannot include query parameters. | +| options | `` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | ##### Examples @@ -376,7 +376,7 @@ Specify the endpoint for this service. | ----------- | ----------------------- | ------------------------------------------------------- | | url | `valueof scalar string` | Server endpoint | | description | `valueof scalar string` | Description of the endpoint | -| parameters | `model Record` | Optional set of parameters used to interpolate the url. | +| parameters | `Record` | Optional set of parameters used to interpolate the url. | ##### Examples diff --git a/packages/json-schema/README.md b/packages/json-schema/README.md index 562a597035..6eba82661b 100644 --- a/packages/json-schema/README.md +++ b/packages/json-schema/README.md @@ -131,9 +131,9 @@ Use `@minContains` and `@maxContains` to customize how many instances to expect. ##### Parameters -| Name | Type | Description | -| ----- | --------------------- | -------------------------------- | -| value | `(intrinsic) unknown` | The type the array must contain. | +| Name | Type | Description | +| ----- | --------- | -------------------------------- | +| value | `unknown` | The type the array must contain. | #### `@contentEncoding` @@ -186,9 +186,9 @@ media type and encoding. ##### Parameters -| Name | Type | Description | -| ----- | --------------------- | --------------------------------- | -| value | `(intrinsic) unknown` | the schema of the string contents | +| Name | Type | Description | +| ----- | --------- | --------------------------------- | +| value | `unknown` | the schema of the string contents | #### `@extension` @@ -204,14 +204,14 @@ emit the raw JSON code `{x: "value"}`. ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters | Name | Type | Description | | ----- | ----------------------- | --------------------------------------------------------------------------------------- | | key | `valueof scalar string` | the name of the keyword of vendor extension, e.g. `x-custom`. | -| value | `(intrinsic) unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | +| value | `unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | #### `@id` @@ -226,7 +226,7 @@ By default, the id will be constructed based on the declaration's name. ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters @@ -248,7 +248,7 @@ you can provide the id. ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters @@ -362,9 +362,9 @@ Specify that the target array must begin with the provided types. ##### Parameters -| Name | Type | Description | -| ----- | ----------------- | --------------------------------------------------------------------------- | -| value | `model unknown[]` | a tuple containing the types that must be present at the start of the array | +| Name | Type | Description | +| ----- | ------- | --------------------------------------------------------------------------- | +| value | `Array` | a tuple containing the types that must be present at the start of the array | #### `@uniqueItems` diff --git a/packages/openapi/README.md b/packages/openapi/README.md index 83ffdf1fd2..202f8d8e29 100644 --- a/packages/openapi/README.md +++ b/packages/openapi/README.md @@ -58,10 +58,10 @@ Attach some custom data to the OpenAPI element generated from this type. ##### Parameters -| Name | Type | Description | -| ----- | --------------------- | ----------------------------------- | -| key | valueof scalar string | Extension key. Must start with `x-` | -| value | `unknown` | Extension value. | +| Name | Type | Description | +| ----- | ----------------------- | ----------------------------------- | +| key | `valueof scalar string` | Extension key. Must start with `x-` | +| value | `unknown` | Extension value. | ##### Examples @@ -90,10 +90,10 @@ Specify the OpenAPI `externalDocs` property for this type. ##### Parameters -| Name | Type | Description | -| ----------- | --------------------- | ----------------------- | -| url | valueof scalar string | Url to the docs | -| description | valueof scalar string | Description of the docs | +| Name | Type | Description | +| ----------- | ----------------------- | ----------------------- | +| url | `valueof scalar string` | Url to the docs | +| description | `valueof scalar string` | Description of the docs | ##### Examples @@ -138,9 +138,9 @@ Specify the OpenAPI `operationId` property for this operation. ##### Parameters -| Name | Type | Description | -| ----------- | --------------------- | ------------------- | -| operationId | valueof scalar string | Operation id value. | +| Name | Type | Description | +| ----------- | ----------------------- | ------------------- | +| operationId | `valueof scalar string` | Operation id value. | ##### Examples diff --git a/packages/protobuf/README.md b/packages/protobuf/README.md index 15d2af2b6b..c3325f7b2b 100644 --- a/packages/protobuf/README.md +++ b/packages/protobuf/README.md @@ -101,7 +101,7 @@ This decorator will force the emitter to check and emit a model. ##### Target -`model {}` +`` ##### Parameters @@ -122,9 +122,9 @@ single Protobuf file. ##### Parameters -| Name | Type | Description | -| ------- | ---------------------------------------- | ----------------------------------- | -| details | `model TypeSpec.Protobuf.PackageDetails` | the optional details of the package | +| Name | Type | Description | +| ------- | ----------------------------------- | ----------------------------------- | +| details | [`PackageDetails`](#packagedetails) | the optional details of the package | #### `@reserve` @@ -155,7 +155,7 @@ information. ##### Target -`model {}` +`` ##### Parameters @@ -204,9 +204,9 @@ Set the streaming mode of an operation. See [StreamMode](./data-types#TypeSpec.P ##### Parameters -| Name | Type | Description | -| ---- | ----------------------------------- | ---------------------------------------------- | -| mode | `enum TypeSpec.Protobuf.StreamMode` | The streaming mode to apply to this operation. | +| Name | Type | Description | +| ---- | --------------------------- | ---------------------------------------------- | +| mode | [`StreamMode`](#streammode) | The streaming mode to apply to this operation. | ##### Examples diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index cd64b12ae7..22a3d4316d 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -167,9 +167,9 @@ export class MarkdownRenderer { `${this.filename(namedType)}#${this.anchorId(namedType)}` ); } - return "name" in type && typeof type.name === "string" - ? inlinecode(type.name) - : getTypeSignature(type); + return inlinecode( + "name" in type && typeof type.name === "string" ? type.name : getTypeSignature(type) + ); } enum(e: EnumRefDoc): MarkdownDoc { diff --git a/packages/versioning/README.md b/packages/versioning/README.md index 22d0b9eca8..7494739cd0 100644 --- a/packages/versioning/README.md +++ b/packages/versioning/README.md @@ -196,10 +196,10 @@ Identifies when the target type changed. ##### Parameters -| Name | Type | Description | -| ------- | --------------------- | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `(intrinsic) unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | -------------------------------------------- | +| version | `EnumMember` | The version that the target type changed in. | +| oldType | `unknown` | The previous type of the target. | #### `@typeChangedFrom` @@ -215,10 +215,10 @@ Identifies when the target type changed. ##### Parameters -| Name | Type | Description | -| ------- | --------------------- | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `(intrinsic) unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | -------------------------------------------- | +| version | `EnumMember` | The version that the target type changed in. | +| oldType | `unknown` | The previous type of the target. | #### `@useDependency` @@ -234,9 +234,9 @@ Identifies that a namespace or a given versioning enum member relies upon a vers ##### Parameters -| Name | Type | Description | -| -------------- | -------------------- | --------------------------------------------------------------------- | -| versionRecords | `model EnumMember[]` | The dependent library version(s) for the target namespace or version. | +| Name | Type | Description | +| -------------- | ------- | --------------------------------------------------------------------- | +| versionRecords | `Array` | The dependent library version(s) for the target namespace or version. | ##### Examples diff --git a/packages/website/.scripts/regen-compiler-docs.mjs b/packages/website/.scripts/regen-compiler-docs.mjs index 8d051d898e..9fed065963 100644 --- a/packages/website/.scripts/regen-compiler-docs.mjs +++ b/packages/website/.scripts/regen-compiler-docs.mjs @@ -39,9 +39,9 @@ async function generateCompilerDocs() { const results = await resolveLibraryRefDocsBase(compilerPath, { namespaces: { include: ["TypeSpec"] }, }); - const renderer = new DocusaurusRenderer(); assert(results, "Unexpected ref doc should have been resolved for compiler."); const [refDoc, diagnostics] = results; + const renderer = new DocusaurusRenderer(refDoc); const decoratorContent = renderDecoratorFile(renderer, refDoc, { title: "Built-in Decorators" }); assert(decoratorContent, "Unexpected decorator file shouldn't be empty for compiler."); await writeFile(join(outputDir, "built-in-decorators.md"), decoratorContent); From d9cfe6da80258668412d8ce72e95374d00579695 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 14:27:32 -0800 Subject: [PATCH 05/24] Create ref-docs-models-2024-1-23-22-27-5.md --- .chronus/changes/ref-docs-models-2024-1-23-22-27-5.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 .chronus/changes/ref-docs-models-2024-1-23-22-27-5.md diff --git a/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md b/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md new file mode 100644 index 0000000000..f56cae7323 --- /dev/null +++ b/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md @@ -0,0 +1,11 @@ +--- +# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking +changeKind: internal +packages: + - "@typespec/http" + - "@typespec/json-schema" + - "@typespec/openapi" + - "@typespec/protobuf" + - "@typespec/versioning" +--- + From e657708347c7930d322e8254b6438f109b66d30d Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 14:38:52 -0800 Subject: [PATCH 06/24] Indexer --- packages/openapi/src/decorators.ts | 2 +- packages/tspd/src/ref-doc/emitters/markdown.ts | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/openapi/src/decorators.ts b/packages/openapi/src/decorators.ts index f86ee54f6c..4f9a5921d1 100644 --- a/packages/openapi/src/decorators.ts +++ b/packages/openapi/src/decorators.ts @@ -107,7 +107,7 @@ const externalDocsKey = createStateSymbol("externalDocs"); /** * Allows referencing an external resource for extended documentation. * @param url The URL for the target documentation. Value MUST be in the format of a URL. - * @param @optional description A short description of the target documentation. + * @param description A short description of the target documentation. */ export function $externalDocs( context: DecoratorContext, diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 22a3d4316d..0624465546 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -154,6 +154,9 @@ export class MarkdownRenderer { prop.doc, ]; }), + ...(model.type.indexer + ? [["", this.ref(model.type.indexer.value), "Additional properties"]] + : []), ]) ); return section("Properties", content); From 48ff6d583e19b89b64fabb41f761a69fbf33f407 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 15:26:55 -0800 Subject: [PATCH 07/24] Fix --- docs/standard-library/built-in-decorators.md | 2 +- .../tspd/src/ref-doc/emitters/docusaurus.ts | 3 --- .../website/.scripts/regen-compiler-docs.mjs | 23 ++++++++++++++++++- packages/website/.scripts/tsconfig.json | 2 +- 4 files changed, 24 insertions(+), 6 deletions(-) diff --git a/docs/standard-library/built-in-decorators.md b/docs/standard-library/built-in-decorators.md index e50c1d5bd6..badf8d098c 100644 --- a/docs/standard-library/built-in-decorators.md +++ b/docs/standard-library/built-in-decorators.md @@ -785,7 +785,7 @@ Mark this namespace as describing a service and configure service properties. #### Parameters | Name | Type | Description | |------|------|-------------| -| options | [`ServiceOptions`](./data-types.md#ServiceOptions) | Optional configuration for the service. | +| options | [`ServiceOptions`](./built-in-data-types.md#ServiceOptions) | Optional configuration for the service. | #### Examples diff --git a/packages/tspd/src/ref-doc/emitters/docusaurus.ts b/packages/tspd/src/ref-doc/emitters/docusaurus.ts index 7b086ba172..585ffb0823 100644 --- a/packages/tspd/src/ref-doc/emitters/docusaurus.ts +++ b/packages/tspd/src/ref-doc/emitters/docusaurus.ts @@ -250,9 +250,6 @@ function renderLinter( } export class DocusaurusRenderer extends MarkdownRenderer { - constructor(refDoc: TypeSpecLibraryRefDoc) { - super(refDoc); - } headingTitle(item: NamedTypeRefDoc): string { // Set an explicit anchor id. return `${inlinecode(item.name)} {#${item.id}}`; diff --git a/packages/website/.scripts/regen-compiler-docs.mjs b/packages/website/.scripts/regen-compiler-docs.mjs index 9fed065963..2833576bd4 100644 --- a/packages/website/.scripts/regen-compiler-docs.mjs +++ b/packages/website/.scripts/regen-compiler-docs.mjs @@ -17,6 +17,26 @@ export const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../ const diagnostics = new Map(); +class CompilerDocusaurusRenderer extends DocusaurusRenderer { + /** + * @param {import("../../tspd/dist/src/ref-doc/types.js").RefDocEntity} type + */ + filename(type) { + switch (type.kind) { + case "decorator": + return "./built-in-decorators.md"; + case "model": + case "enum": + case "union": + return "./built-in-data-types.md"; + case "operation": + case "interface": + default: + return ""; + } + } +} + // Compiler const compilerDiag = await generateCompilerDocs(); if (compilerDiag.length) { @@ -40,8 +60,9 @@ async function generateCompilerDocs() { namespaces: { include: ["TypeSpec"] }, }); assert(results, "Unexpected ref doc should have been resolved for compiler."); + /** @type {*} */ const [refDoc, diagnostics] = results; - const renderer = new DocusaurusRenderer(refDoc); + const renderer = new CompilerDocusaurusRenderer(refDoc); const decoratorContent = renderDecoratorFile(renderer, refDoc, { title: "Built-in Decorators" }); assert(decoratorContent, "Unexpected decorator file shouldn't be empty for compiler."); await writeFile(join(outputDir, "built-in-decorators.md"), decoratorContent); diff --git a/packages/website/.scripts/tsconfig.json b/packages/website/.scripts/tsconfig.json index c9961df8a3..a7730eb755 100644 --- a/packages/website/.scripts/tsconfig.json +++ b/packages/website/.scripts/tsconfig.json @@ -1,5 +1,5 @@ { - "extends": "../../tsconfig.json", + "extends": "../../../tsconfig.base.json", "compilerOptions": { "allowJs": true }, From 1f3503cb05d4f8a5d70c79f45bc576ba554f58e8 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 15:37:27 -0800 Subject: [PATCH 08/24] Handle nested types --- .../tspd/src/ref-doc/emitters/markdown.ts | 53 +++++++++++++------ 1 file changed, 38 insertions(+), 15 deletions(-) diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 0624465546..4fe69a9e5c 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -8,6 +8,7 @@ import { ExampleRefDoc, InterfaceRefDoc, LinterRuleRefDoc, + ModelPropertyRefDoc, ModelRefDoc, NamedTypeRefDoc, NamespaceRefDoc, @@ -144,24 +145,46 @@ export class MarkdownRenderer { modelProperties(model: ModelRefDoc) { const content: MarkdownDoc = []; - content.push( - table([ - ["Name", "Type", "Description"], - ...[...model.properties.values()].map((prop) => { - return [ - `${prop.name}${prop.type.optional ? "?" : ""}`, - this.ref(prop.type.type), - prop.doc, - ]; - }), - ...(model.type.indexer - ? [["", this.ref(model.type.indexer.value), "Additional properties"]] - : []), - ]) - ); + const rows: { name: string; type: string; doc: string }[] = [ + { name: "Name", type: "Type", doc: "Description" }, + ]; + + for (const prop of model.properties.values()) { + const propRows = this.modelPropertyRows(prop); + for (const row of propRows) { + rows.push(row); + } + } + if (model.type.indexer) { + rows.push({ + name: "", + type: this.ref(model.type.indexer.value), + doc: "Additional properties", + }); + } + content.push(table(rows.map((x) => [x.name, x.type, x.doc]))); return section("Properties", content); } + modelPropertyRows(prop: ModelPropertyRefDoc): { name: string; type: string; doc: string }[] { + const base = { + name: `${prop.name}${prop.type.optional ? "?" : ""}`, + type: this.ref(prop.type.type), + doc: prop.doc, + }; + if (prop.type.type.kind === "Model" && prop.type.type.name === "") { + return [ + base, + ...[...prop.type.type.properties.values()].map((x) => ({ + name: `${prop.name}.${x.name}`, + type: this.ref(x.type), + doc: "", + })), + ]; + } + return [base]; + } + ref(type: Type | ValueType): string { const namedType = type.kind !== "Value" && this.refDoc.getNamedTypeRefDoc(type); if (namedType) { From a87cfe2d115e4f209ba893faef1eec762e599261 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 15:37:46 -0800 Subject: [PATCH 09/24] . --- packages/tspd/src/ref-doc/emitters/markdown.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 4fe69a9e5c..f54385ca24 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -176,7 +176,7 @@ export class MarkdownRenderer { return [ base, ...[...prop.type.type.properties.values()].map((x) => ({ - name: `${prop.name}.${x.name}`, + name: `${prop.name}.${x.name}${prop.type.optional ? "?" : ""}`, type: this.ref(x.type), doc: "", })), From c59670c1fa66fe4569e32e57ae673ec2abc56711 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 15:59:22 -0800 Subject: [PATCH 10/24] Better string type name --- docs/libraries/http/reference/data-types.md | 16 ++++++++-------- docs/libraries/rest/reference/decorators.md | 8 ++++---- .../compiler/src/core/helpers/type-name-utils.ts | 1 + packages/rest/README.md | 8 ++++---- 4 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/libraries/http/reference/data-types.md b/docs/libraries/http/reference/data-types.md index 05232ad9b7..43024dcbe4 100644 --- a/docs/libraries/http/reference/data-types.md +++ b/docs/libraries/http/reference/data-types.md @@ -229,10 +229,10 @@ model TypeSpec.Http.HeaderOptions #### Properties -| Name | Type | Description | -| ------- | ------------------------------------------------------------- | --------------------------------------------------------------- | -| name? | `string` | Name of the header when sent over HTTP.
| -| format? | `union csv \| multi \| tsv \| ssv \| pipes \| simple \| form` | Determines the format of the array if type array is used.
| +| Name | Type | Description | +| ------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- | +| name? | `string` | Name of the header when sent over HTTP.
| +| format? | `union "csv" \| "multi" \| "tsv" \| "ssv" \| "pipes" \| "simple" \| "form"` | Determines the format of the array if type array is used.
| ### `ImplicitFlow` {#TypeSpec.Http.ImplicitFlow} @@ -436,10 +436,10 @@ model TypeSpec.Http.QueryOptions #### Properties -| Name | Type | Description | -| ------- | ------------------------------------------------------------- | --------------------------------------------------------------- | -| name? | `string` | Name of the query when included in the url.
| -| format? | `union multi \| csv \| ssv \| tsv \| simple \| form \| pipes` | Determines the format of the array if type array is used.
| +| Name | Type | Description | +| ------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- | +| name? | `string` | Name of the query when included in the url.
| +| format? | `union "multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used.
| ### `Response` {#TypeSpec.Http.Response} diff --git a/docs/libraries/rest/reference/decorators.md b/docs/libraries/rest/reference/decorators.md index 5163353f55..cccfb86be3 100644 --- a/docs/libraries/rest/reference/decorators.md +++ b/docs/libraries/rest/reference/decorators.md @@ -31,7 +31,7 @@ Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my Defines the separator string that is inserted before the action name in auto-generated routes for actions. ```typespec -@TypeSpec.Rest.actionSeparator(seperator: valueof / | : | /:) +@TypeSpec.Rest.actionSeparator(seperator: valueof "/" | ":" | "/:") ``` #### Target @@ -40,9 +40,9 @@ Defines the separator string that is inserted before the action name in auto-gen #### Parameters -| Name | Type | Description | -| --------- | ---------------------------- | ---------------------------------------------------------------- | -| seperator | `valueof union / \| : \| /:` | Seperator seperating the action segment from the rest of the url | +| Name | Type | Description | +| --------- | ---------------------------------- | ---------------------------------------------------------------- | +| seperator | `valueof union "/" \| ":" \| "/:"` | Seperator seperating the action segment from the rest of the url | ### `@autoRoute` {#@TypeSpec.Rest.autoRoute} diff --git a/packages/compiler/src/core/helpers/type-name-utils.ts b/packages/compiler/src/core/helpers/type-name-utils.ts index 32ea713ed9..8bbdd1e8df 100644 --- a/packages/compiler/src/core/helpers/type-name-utils.ts +++ b/packages/compiler/src/core/helpers/type-name-utils.ts @@ -48,6 +48,7 @@ export function getTypeName(type: Type | ValueType, options?: TypeNameOptions): case "StringTemplate": return "string"; case "String": + return `"${type.value}"`; case "Number": case "Boolean": return type.value.toString(); diff --git a/packages/rest/README.md b/packages/rest/README.md index 460db1aee1..8735429f8a 100644 --- a/packages/rest/README.md +++ b/packages/rest/README.md @@ -52,7 +52,7 @@ Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my Defines the separator string that is inserted before the action name in auto-generated routes for actions. ```typespec -@TypeSpec.Rest.actionSeparator(seperator: valueof / | : | /:) +@TypeSpec.Rest.actionSeparator(seperator: valueof "/" | ":" | "/:") ``` ##### Target @@ -61,9 +61,9 @@ Defines the separator string that is inserted before the action name in auto-gen ##### Parameters -| Name | Type | Description | -| --------- | ---------------------------- | ---------------------------------------------------------------- | -| seperator | `valueof union / \| : \| /:` | Seperator seperating the action segment from the rest of the url | +| Name | Type | Description | +| --------- | ---------------------------------- | ---------------------------------------------------------------- | +| seperator | `valueof union "/" \| ":" \| "/:"` | Seperator seperating the action segment from the rest of the url | #### `@autoRoute` From 5a598e71057cf415ccc17729ba6dd54e525b2fe5 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 17:27:34 -0800 Subject: [PATCH 11/24] Create ref-docs-models-2024-1-24-0-0-44.md --- .chronus/changes/ref-docs-models-2024-1-24-0-0-44.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 .chronus/changes/ref-docs-models-2024-1-24-0-0-44.md diff --git a/.chronus/changes/ref-docs-models-2024-1-24-0-0-44.md b/.chronus/changes/ref-docs-models-2024-1-24-0-0-44.md new file mode 100644 index 0000000000..3bf9a27aca --- /dev/null +++ b/.chronus/changes/ref-docs-models-2024-1-24-0-0-44.md @@ -0,0 +1,8 @@ +--- +# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking +changeKind: fix +packages: + - "@typespec/compiler" +--- + +Wrap string in quotes in errors From ac30058772322e43af86baea881b2870a097edec Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 17:27:55 -0800 Subject: [PATCH 12/24] Update ref-docs-models-2024-1-23-22-27-5.md --- .chronus/changes/ref-docs-models-2024-1-23-22-27-5.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md b/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md index f56cae7323..10cc5d1341 100644 --- a/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md +++ b/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md @@ -3,6 +3,7 @@ changeKind: internal packages: - "@typespec/http" + - "@typespec/rest" - "@typespec/json-schema" - "@typespec/openapi" - "@typespec/protobuf" From 23910451f722f61671594bd90ad5a8005a0dde38 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 18:54:54 -0800 Subject: [PATCH 13/24] fix some docs --- packages/compiler/src/config/config-to-options.ts | 2 +- packages/compiler/src/core/decorator-utils.ts | 4 ++-- packages/compiler/src/core/diagnostics.ts | 2 +- packages/compiler/src/core/types.ts | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/compiler/src/config/config-to-options.ts b/packages/compiler/src/config/config-to-options.ts index ee43969dfb..d6778d0ca2 100644 --- a/packages/compiler/src/config/config-to-options.ts +++ b/packages/compiler/src/config/config-to-options.ts @@ -37,7 +37,7 @@ export interface ConfigToOptionsOptions { /** * Resolve the compiler options for the given entrypoint by resolving the tspconfig.yaml. * @param host Compiler host - * @param compilerOptions + * @param options */ export async function resolveCompilerOptions( host: CompilerHost, diff --git a/packages/compiler/src/core/decorator-utils.ts b/packages/compiler/src/core/decorator-utils.ts index 206255d72b..513da7ec03 100644 --- a/packages/compiler/src/core/decorator-utils.ts +++ b/packages/compiler/src/core/decorator-utils.ts @@ -36,10 +36,10 @@ export type InferredTypeSpecValue = /** * Validate the decorator target is matching the expected value. - * @param program + * @param context * @param target - * @param expectedType * @param decoratorName + * @param expectedType * @returns */ export function validateDecoratorTarget( diff --git a/packages/compiler/src/core/diagnostics.ts b/packages/compiler/src/core/diagnostics.ts index f7067e1bdb..feb4b484a5 100644 --- a/packages/compiler/src/core/diagnostics.ts +++ b/packages/compiler/src/core/diagnostics.ts @@ -294,7 +294,7 @@ export function createDiagnosticCollector(): DiagnosticCollector { /** * Ignore the diagnostics emitted by the diagnostic accessor pattern and just return the actual result. - * @param result: Accessor pattern tuple result including the actual result and the list of diagnostics. + * @param result Accessor pattern tuple result including the actual result and the list of diagnostics. * @returns Actual result. */ export function ignoreDiagnostics(result: DiagnosticResult): T { diff --git a/packages/compiler/src/core/types.ts b/packages/compiler/src/core/types.ts index 544a9057b1..48463c7758 100644 --- a/packages/compiler/src/core/types.ts +++ b/packages/compiler/src/core/types.ts @@ -1916,7 +1916,7 @@ export interface CompilerHost { * @param path Path to the directory. * @returns list of file/directory in the given directory. Returns the name not the full path. */ - readDir(dir: string): Promise; + readDir(path: string): Promise; /** * Deletes a directory or file. @@ -2317,7 +2317,7 @@ export interface Tracer { trace(area: string, message: string, target?: DiagnosticTarget): void; /** - * @param area + * @param subarea */ sub(subarea: string): Tracer; } From 203c9a971adf3b459865a74f03c471df2e0ddc8e Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 23 Feb 2024 19:46:28 -0800 Subject: [PATCH 14/24] Add simple model rendering test --- .../tspd/src/ref-doc/emitters/markdown.ts | 2 +- packages/tspd/src/ref-doc/extractor.ts | 7 +- .../tspd/test/emitters/markdown/model.test.ts | 205 ++++++++++++++++++ packages/tspd/test/test-utils.ts | 16 ++ 4 files changed, 226 insertions(+), 4 deletions(-) create mode 100644 packages/tspd/test/emitters/markdown/model.test.ts create mode 100644 packages/tspd/test/test-utils.ts diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index f54385ca24..9b3912478a 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -176,7 +176,7 @@ export class MarkdownRenderer { return [ base, ...[...prop.type.type.properties.values()].map((x) => ({ - name: `${prop.name}.${x.name}${prop.type.optional ? "?" : ""}`, + name: `${prop.name}.${x.name}${x.optional ? "?" : ""}`, type: this.ref(x.type), doc: "", })), diff --git a/packages/tspd/src/ref-doc/extractor.ts b/packages/tspd/src/ref-doc/extractor.ts index 5c1fbe8af1..9e13411167 100644 --- a/packages/tspd/src/ref-doc/extractor.ts +++ b/packages/tspd/src/ref-doc/extractor.ts @@ -160,6 +160,7 @@ function resolveNamespaces( } return diagnostics.wrap(namespaceTypes); } + export function extractRefDocs( program: Program, options: ExtractRefDocOptions = {} @@ -502,13 +503,13 @@ function extractScalarRefDocs(program: Program, type: Scalar): ScalarRefDoc { } function extractMainDoc(program: Program, type: Type): string { - let mainDoc: string = ""; + const mainDocs: string[] = []; for (const doc of type.node?.docs ?? []) { for (const dContent of doc.content) { - mainDoc += dContent.text + "\n"; + mainDocs.push(dContent.text); } } - return mainDoc !== "" ? mainDoc : getDoc(program, type) ?? ""; + return mainDocs.length > 0 ? mainDocs.join("\n") : getDoc(program, type) ?? ""; } function extractExamples(type: Type): ExampleRefDoc[] { diff --git a/packages/tspd/test/emitters/markdown/model.test.ts b/packages/tspd/test/emitters/markdown/model.test.ts new file mode 100644 index 0000000000..d97fc1c518 --- /dev/null +++ b/packages/tspd/test/emitters/markdown/model.test.ts @@ -0,0 +1,205 @@ +import { ok } from "assert"; +import { describe, expect, it } from "vitest"; +import { renderMarkdowDoc } from "../../../src/ref-doc/utils/markdown.js"; +import { createMarkdownRenderer } from "../../test-utils.js"; + +async function renderModel(code: string) { + const { renderer, refDoc } = await createMarkdownRenderer(`namespace Lib; ${code}`); + const fooModel = refDoc.namespaces[0].models.find((x) => x.name === "Test"); + ok(fooModel, "Expected a model named `Test`"); + return renderMarkdowDoc(renderer.model(fooModel)); +} + +it("render simple model", async () => { + const result = await renderModel(`model Test {}`); + expect(result).toEqual( + [ + "# `Test`", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "", + "## Properties", + "| Name | Type | Description |", + "|------|------|-------------|", + ].join("\n") + ); +}); + +it("render model with template parameter", async () => { + const result = await renderModel(`model Test {}`); + expect(result).toEqual( + [ + "# `Test`", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "## Template Parameters", + "| Name | Description |", + "|------|-------------|", + "| T | |", + "", + "", + "## Properties", + "| Name | Type | Description |", + "|------|------|-------------|", + ].join("\n") + ); +}); + +describe("model examples", () => { + it("render single example", async () => { + const result = await renderModel(` + /** + * @example + * \`\`\`tsp + * model Foo {test: Test} + * \`\`\` + */ + model Test {} + `); + expect(result).toEqual( + [ + "# `Test`", + "", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "## Examples", + "", + "```tsp", + "model Foo {test: Test}", + "```", + "", + "## Properties", + "| Name | Type | Description |", + "|------|------|-------------|", + ].join("\n") + ); + }); + + it("render named example", async () => { + const result = await renderModel(` + /** + * @example First Example + * \`\`\`tsp + * model Foo {test1: Test} + * \`\`\` + * @example Second Example + * \`\`\`tsp + * model Foo {test2: Test} + * \`\`\` + */ + model Test {} + `); + expect(result).toEqual( + [ + "# `Test`", + "", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "## Examples", + "### First Example", + "", + "```tsp", + "model Foo {test1: Test}", + "```", + "", + "### Second Example", + "", + "```tsp", + "model Foo {test2: Test}", + "```", + "", + "## Properties", + "| Name | Type | Description |", + "|------|------|-------------|", + ].join("\n") + ); + }); +}); + +describe("properties table", () => { + const common = [ + "# `Test`", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "", + "## Properties", + "| Name | Type | Description |", + "|------|------|-------------|", + ]; + async function expectTable({ code, rows }: { code: string; rows: string[] }) { + const result = await renderModel(code); + expect(result).toEqual([...common, ...rows].join("\n")); + } + it("render properties without docs", async () => { + await expectTable({ + code: `model Test { name: string, other: int32 }`, + rows: ["| name | `string` | |", "| other | `int32` | |"], + }); + }); + + it("render properties with documentation", async () => { + await expectTable({ + code: `model Test { + /** name of the test */ + name: string; + /** other of the test */ + other: int32; + }`, + rows: ["| name | `string` | name of the test |", "| other | `int32` | other of the test |"], + }); + }); + + it("render optional properties", async () => { + await expectTable({ + code: `model Test { name?: string, other: int32 }`, + rows: ["| name? | `string` | |", "| other | `int32` | |"], + }); + }); + + it("render link to local type", async () => { + await expectTable({ + code: `model Test { other: Other } model Other {name: string}`, + rows: ["| other | [`Other`](#other) | |"], + }); + }); + + it("render indexer", async () => { + await expectTable({ + code: `model Test is Record { name: string }`, + rows: ["| name | `string` | |", "| | `string` | Additional properties |"], + }); + }); + + it("flatten nested anonymous model", async () => { + await expectTable({ + code: `model Test { name: string, nested: {val: string, age: int32, third?: boolean} }`, + rows: [ + "| name | `string` | |", + "| nested | `` | |", + "| nested.val | `string` | |", + "| nested.age | `int32` | |", + "| nested.third? | `boolean` | |", + ], + }); + }); +}); diff --git a/packages/tspd/test/test-utils.ts b/packages/tspd/test/test-utils.ts new file mode 100644 index 0000000000..526f8c5e4f --- /dev/null +++ b/packages/tspd/test/test-utils.ts @@ -0,0 +1,16 @@ +import { createTestHost, expectDiagnosticEmpty } from "@typespec/compiler/testing"; +import { MarkdownRenderer } from "../src/ref-doc/emitters/markdown.js"; +import { extractRefDocs } from "../src/ref-doc/extractor.js"; + +export async function extractTestRefDoc(code: string) { + const host = await createTestHost(); + host.addTypeSpecFile("main.tsp", code); + await host.compile("main.tsp"); + return extractRefDocs(host.program); +} + +export async function createMarkdownRenderer(code: string) { + const [refDoc, diagnostics] = await extractTestRefDoc(code); + expectDiagnosticEmpty(diagnostics); + return { renderer: new MarkdownRenderer(refDoc as any), refDoc }; +} From e221aeae1a635d19b8671082069fc0f5c3fa546c Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 26 Feb 2024 08:52:45 -0800 Subject: [PATCH 15/24] fix tests --- packages/compiler/test/checker/model.test.ts | 6 +++--- packages/compiler/test/checker/relation.test.ts | 8 ++++---- packages/compiler/test/checker/templates.test.ts | 2 +- packages/compiler/test/decorators/decorators.test.ts | 4 ++-- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/compiler/test/checker/model.test.ts b/packages/compiler/test/checker/model.test.ts index 5f3ed2e633..81ce85ac5e 100644 --- a/packages/compiler/test/checker/model.test.ts +++ b/packages/compiler/test/checker/model.test.ts @@ -129,10 +129,10 @@ describe("compiler: models", () => { describe("doesn't allow a default of different type than the property type", () => { const testCases: [string, string, string][] = [ ["string", "123", "Type '123' is not assignable to type 'string'"], - ["int32", `"foo"`, "Type 'foo' is not assignable to type 'int32'"], - ["boolean", `"foo"`, "Type 'foo' is not assignable to type 'boolean'"], + ["int32", `"foo"`, `Type '"foo"' is not assignable to type 'int32'`], + ["boolean", `"foo"`, `Type '"foo"' is not assignable to type 'boolean'`], ["string[]", `["foo", 123]`, `Type '123' is not assignable to type 'string'`], - [`"foo" | "bar"`, `"foo1"`, "Type 'foo1' is not assignable to type 'foo | bar'"], + [`"foo" | "bar"`, `"foo1"`, `Type '"foo1"' is not assignable to type '"foo" | "bar"'`], ]; for (const [type, defaultValue, errorMessage] of testCases) { diff --git a/packages/compiler/test/checker/relation.test.ts b/packages/compiler/test/checker/relation.test.ts index 308d2cd5a7..91ece1a3d0 100644 --- a/packages/compiler/test/checker/relation.test.ts +++ b/packages/compiler/test/checker/relation.test.ts @@ -239,7 +239,7 @@ describe("compiler: checker: type relations", () => { { source: `"bar"`, target: `"foo"` }, { code: "unassignable", - message: "Type 'bar' is not assignable to type 'foo'", + message: `Type '"bar"' is not assignable to type '"foo"'`, } ); }); @@ -249,7 +249,7 @@ describe("compiler: checker: type relations", () => { { source: `string`, target: `"foo"` }, { code: "unassignable", - message: "Type 'string' is not assignable to type 'foo'", + message: `Type 'string' is not assignable to type '"foo"'`, } ); }); @@ -1102,7 +1102,7 @@ describe("compiler: checker: type relations", () => { { source: `"foo bar"`, target: "valueof int16" }, { code: "unassignable", - message: "Type 'foo bar' is not assignable to type 'int16'", + message: `Type '"foo bar"' is not assignable to type 'int16'`, } ); }); @@ -1128,7 +1128,7 @@ describe("compiler: checker: type relations", () => { { source: `"foo bar"`, target: "valueof float32" }, { code: "unassignable", - message: "Type 'foo bar' is not assignable to type 'float32'", + message: `Type '"foo bar"' is not assignable to type 'float32'`, } ); }); diff --git a/packages/compiler/test/checker/templates.test.ts b/packages/compiler/test/checker/templates.test.ts index 4538a72c53..1b5ffc97d7 100644 --- a/packages/compiler/test/checker/templates.test.ts +++ b/packages/compiler/test/checker/templates.test.ts @@ -280,7 +280,7 @@ describe("compiler: templates", () => { // Only one error, Bar can't be created as T is not constraint to object expectDiagnostics(diagnostics, { code: "unassignable", - message: "Type 'abc' is not assignable to type '{}'", + message: `Type '"abc"' is not assignable to type '{}'`, pos, }); }); diff --git a/packages/compiler/test/decorators/decorators.test.ts b/packages/compiler/test/decorators/decorators.test.ts index 8cb9d89ac9..e889a767e4 100644 --- a/packages/compiler/test/decorators/decorators.test.ts +++ b/packages/compiler/test/decorators/decorators.test.ts @@ -668,7 +668,7 @@ describe("compiler: built-in decorators", () => { '"int32"', // TODO: Arguably this should be improved. "invalid-argument", - `Argument 'int32' is not assignable to parameter of type 'Scalar'`, + `Argument '"int32"' is not assignable to parameter of type 'Scalar'`, ], ]; describe("valid", () => { @@ -794,7 +794,7 @@ describe("compiler: built-in decorators", () => { expectDiagnostics(diagnostics, { code: "invalid-argument", - message: "Argument 'foo' is not assignable to parameter of type 'Operation'", + message: `Argument '"foo"' is not assignable to parameter of type 'Operation'`, severity: "error", }); }); From 4f08b5bafa7f8d2e952e66e5461d46ec7eb339da Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 26 Feb 2024 09:12:17 -0800 Subject: [PATCH 16/24] more fixes --- packages/http/test/http-decorators.test.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/http/test/http-decorators.test.ts b/packages/http/test/http-decorators.test.ts index 8aafa986b6..a74391c941 100644 --- a/packages/http/test/http-decorators.test.ts +++ b/packages/http/test/http-decorators.test.ts @@ -664,8 +664,7 @@ describe("http: decorators", () => { expectDiagnostics(diagnostics, [ { code: "unassignable", - message: - "Type 'foo' is not assignable to type 'TypeSpec.Http.AuthorizationCodeFlow | TypeSpec.Http.ImplicitFlow | TypeSpec.Http.PasswordFlow | TypeSpec.Http.ClientCredentialsFlow'", + message: `Type '"foo"' is not assignable to type 'TypeSpec.Http.AuthorizationCodeFlow | TypeSpec.Http.ImplicitFlow | TypeSpec.Http.PasswordFlow | TypeSpec.Http.ClientCredentialsFlow'`, }, { code: "unassignable", From 046f3dcc2c3e64120da973be07b92be59d08a072 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 26 Feb 2024 09:15:55 -0800 Subject: [PATCH 17/24] more fixes --- packages/rest/package.json | 1 + packages/rest/test/routes.test.ts | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/rest/package.json b/packages/rest/package.json index 2389ca1e81..8d3bdfae3a 100644 --- a/packages/rest/package.json +++ b/packages/rest/package.json @@ -38,6 +38,7 @@ "watch": "tsc -p . --watch", "lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit", "test": "vitest run", + "test:watch": "vitest --watch", "test:ui": "vitest --ui", "test-official": "vitest run --coverage --reporter=junit --reporter=default --no-file-parallelism", "lint": "eslint . --ext .ts --max-warnings=0", diff --git a/packages/rest/test/routes.test.ts b/packages/rest/test/routes.test.ts index 7e7be9ba95..b070d47419 100644 --- a/packages/rest/test/routes.test.ts +++ b/packages/rest/test/routes.test.ts @@ -425,7 +425,7 @@ describe("rest: routes", () => { strictEqual(diagnostics[0].code, "invalid-argument"); strictEqual( diagnostics[0].message, - `Argument 'x' is not assignable to parameter of type 'valueof / | : | /:'` + `Argument '"x"' is not assignable to parameter of type 'valueof "/" | ":" | "/:"'` ); }); From 5c7b2a8250141f7f82945d94571698d47d9a6574 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 26 Feb 2024 09:57:49 -0800 Subject: [PATCH 18/24] fix extra br --- docs/libraries/http/reference/data-types.md | 24 +++++------ .../libraries/openapi/reference/data-types.md | 28 ++++++------- .../protobuf/reference/data-types.md | 8 ++-- docs/standard-library/built-in-data-types.md | 42 +------------------ docs/standard-library/built-in-decorators.md | 39 ----------------- 5 files changed, 32 insertions(+), 109 deletions(-) diff --git a/docs/libraries/http/reference/data-types.md b/docs/libraries/http/reference/data-types.md index 43024dcbe4..87c0607427 100644 --- a/docs/libraries/http/reference/data-types.md +++ b/docs/libraries/http/reference/data-types.md @@ -229,10 +229,10 @@ model TypeSpec.Http.HeaderOptions #### Properties -| Name | Type | Description | -| ------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- | -| name? | `string` | Name of the header when sent over HTTP.
| -| format? | `union "csv" \| "multi" \| "tsv" \| "ssv" \| "pipes" \| "simple" \| "form"` | Determines the format of the array if type array is used.
| +| Name | Type | Description | +| ------- | --------------------------------------------------------------------------- | --------------------------------------------------------- | +| name? | `string` | Name of the header when sent over HTTP. | +| format? | `union "csv" \| "multi" \| "tsv" \| "ssv" \| "pipes" \| "simple" \| "form"` | Determines the format of the array if type array is used. | ### `ImplicitFlow` {#TypeSpec.Http.ImplicitFlow} @@ -384,10 +384,10 @@ model TypeSpec.Http.OpenIdConnectAuth #### Properties -| Name | Type | Description | -| ---------------- | --------------- | ----------------------------------------------------------------- | -| type | `openIdConnect` | Auth type
| -| openIdConnectUrl | `ConnectUrl` | Connect url. It can be specified relative to the server URL
| +| Name | Type | Description | +| ---------------- | --------------- | ----------------------------------------------------------- | +| type | `openIdConnect` | Auth type | +| openIdConnectUrl | `ConnectUrl` | Connect url. It can be specified relative to the server URL | ### `PasswordFlow` {#TypeSpec.Http.PasswordFlow} @@ -436,10 +436,10 @@ model TypeSpec.Http.QueryOptions #### Properties -| Name | Type | Description | -| ------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- | -| name? | `string` | Name of the query when included in the url.
| -| format? | `union "multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used.
| +| Name | Type | Description | +| ------- | --------------------------------------------------------------------------- | --------------------------------------------------------- | +| name? | `string` | Name of the query when included in the url. | +| format? | `union "multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used. | ### `Response` {#TypeSpec.Http.Response} diff --git a/docs/libraries/openapi/reference/data-types.md b/docs/libraries/openapi/reference/data-types.md index 32b92bd61c..98635d691c 100644 --- a/docs/libraries/openapi/reference/data-types.md +++ b/docs/libraries/openapi/reference/data-types.md @@ -18,11 +18,11 @@ model TypeSpec.OpenAPI.AdditionalInfo #### Properties -| Name | Type | Description | -| --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- | -| termsOfService? | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
| -| contact? | [`Contact`](./data-types.md#TypeSpec.OpenAPI.Contact) | The contact information for the exposed API.
| -| license? | [`License`](./data-types.md#TypeSpec.OpenAPI.License) | The license information for the exposed API.
| +| Name | Type | Description | +| --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- | +| termsOfService? | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL. | +| contact? | [`Contact`](./data-types.md#TypeSpec.OpenAPI.Contact) | The contact information for the exposed API. | +| license? | [`License`](./data-types.md#TypeSpec.OpenAPI.License) | The license information for the exposed API. | ### `Contact` {#TypeSpec.OpenAPI.Contact} @@ -34,11 +34,11 @@ model TypeSpec.OpenAPI.Contact #### Properties -| Name | Type | Description | -| ------ | -------- | ------------------------------------------------------------------------------------------------------ | -| name? | `string` | The identifying name of the contact person/organization.
| -| url? | `url` | The URL pointing to the contact information. MUST be in the format of a URL.
| -| email? | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
| +| Name | Type | Description | +| ------ | -------- | ------------------------------------------------------------------------------------------------ | +| name? | `string` | The identifying name of the contact person/organization. | +| url? | `url` | The URL pointing to the contact information. MUST be in the format of a URL. | +| email? | `string` | The email address of the contact person/organization. MUST be in the format of an email address. | ### `License` {#TypeSpec.OpenAPI.License} @@ -50,7 +50,7 @@ model TypeSpec.OpenAPI.License #### Properties -| Name | Type | Description | -| ---- | -------- | ---------------------------------------------------------------------------- | -| name | `string` | The license name used for the API.
| -| url? | `url` | A URL to the license used for the API. MUST be in the format of a URL.
| +| Name | Type | Description | +| ---- | -------- | ---------------------------------------------------------------------- | +| name | `string` | The license name used for the API. | +| url? | `url` | A URL to the license used for the API. MUST be in the format of a URL. | diff --git a/docs/libraries/protobuf/reference/data-types.md b/docs/libraries/protobuf/reference/data-types.md index 603427920e..ec981dc207 100644 --- a/docs/libraries/protobuf/reference/data-types.md +++ b/docs/libraries/protobuf/reference/data-types.md @@ -80,10 +80,10 @@ model TypeSpec.Protobuf.PackageDetails #### Properties -| Name | Type | Description | -| -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| name? | `string` | The package's name.

By default, the package's name is constructed from the namespace it is applied to.
| -| options? | `Record` | The package's top-level options.

See the [Protobuf Language Guide - Options](https://protobuf.dev/programming-guides/proto3/#options) for more information.

Currently, only string, boolean, and numeric options are supported.
| +| Name | Type | Description | +| -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name? | `string` | The package's name.

By default, the package's name is constructed from the namespace it is applied to. | +| options? | `Record` | The package's top-level options.

See the [Protobuf Language Guide - Options](https://protobuf.dev/programming-guides/proto3/#options) for more information.

Currently, only string, boolean, and numeric options are supported. | ### `StreamMode` {#TypeSpec.Protobuf.StreamMode} diff --git a/docs/standard-library/built-in-data-types.md b/docs/standard-library/built-in-data-types.md index 0bc4fc5ac2..e6ff74a9a7 100644 --- a/docs/standard-library/built-in-data-types.md +++ b/docs/standard-library/built-in-data-types.md @@ -9,7 +9,6 @@ toc_max_heading_level: 3 - ```typespec model Array ``` @@ -27,7 +26,6 @@ model Array ### `DefaultKeyVisibility` {#DefaultKeyVisibility} Applies a visibility setting to a collection of properties. - ```typespec model DefaultKeyVisibility ``` @@ -46,7 +44,6 @@ model DefaultKeyVisibility ### `object` {#object} Represent a model - ```typespec model object ``` @@ -59,7 +56,6 @@ model object ### `OmitDefaults` {#OmitDefaults} Represents a collection of properties with default values omitted. - ```typespec model OmitDefaults ``` @@ -77,7 +73,6 @@ model OmitDefaults ### `OmitProperties` {#OmitProperties} Represents a collection of omitted properties. - ```typespec model OmitProperties ``` @@ -96,7 +91,6 @@ model OmitProperties ### `OptionalProperties` {#OptionalProperties} Represents a collection of optional properties. - ```typespec model OptionalProperties ``` @@ -115,7 +109,6 @@ model OptionalProperties - ```typespec model Record ``` @@ -133,7 +126,6 @@ model Record ### `ServiceOptions` {#ServiceOptions} Service options. - ```typespec model ServiceOptions ``` @@ -142,13 +134,12 @@ model ServiceOptions #### Properties | Name | Type | Description | |------|------|-------------| -| title? | [`string`](#string) | Title of the service.
| -| version? | [`string`](#string) | Version of the service.
| +| title? | [`string`](#string) | Title of the service. | +| version? | [`string`](#string) | Version of the service. | ### `UpdateableProperties` {#UpdateableProperties} Represents a collection of updateable properties. - ```typespec model UpdateableProperties ``` @@ -166,7 +157,6 @@ model UpdateableProperties ### `BytesKnownEncoding` {#BytesKnownEncoding} Known encoding to use on bytes - ```typespec enum BytesKnownEncoding ``` @@ -176,7 +166,6 @@ enum BytesKnownEncoding ### `DateTimeKnownEncoding` {#DateTimeKnownEncoding} Known encoding to use on utcDateTime or offsetDateTime - ```typespec enum DateTimeKnownEncoding ``` @@ -186,7 +175,6 @@ enum DateTimeKnownEncoding ### `DurationKnownEncoding` {#DurationKnownEncoding} Known encoding to use on duration - ```typespec enum DurationKnownEncoding ``` @@ -196,7 +184,6 @@ enum DurationKnownEncoding ### `boolean` {#boolean} Boolean with `true` and `false` values. - ```typespec scalar boolean ``` @@ -206,7 +193,6 @@ scalar boolean ### `bytes` {#bytes} Represent a byte array - ```typespec scalar bytes ``` @@ -217,7 +203,6 @@ scalar bytes A decimal number with any length and precision. This represent any `decimal` value possible. It is commonly represented as `BigDecimal` in some languages. - ```typespec scalar decimal ``` @@ -227,7 +212,6 @@ scalar decimal ### `decimal128` {#decimal128} A 128-bit decimal number. - ```typespec scalar decimal128 ``` @@ -237,7 +221,6 @@ scalar decimal128 ### `duration` {#duration} A duration/time period. e.g 5s, 10h - ```typespec scalar duration ``` @@ -247,7 +230,6 @@ scalar duration ### `float` {#float} A number with decimal value - ```typespec scalar float ``` @@ -257,7 +239,6 @@ scalar float ### `float32` {#float32} A 32 bit floating point number. (`±5.0 × 10^−324` to `±1.7 × 10^308`) - ```typespec scalar float32 ``` @@ -267,7 +248,6 @@ scalar float32 ### `float64` {#float64} A 32 bit floating point number. (`±1.5 x 10^−45` to `±3.4 x 10^38`) - ```typespec scalar float64 ``` @@ -277,7 +257,6 @@ scalar float64 ### `int16` {#int16} A 16-bit integer. (`-32,768` to `32,767`) - ```typespec scalar int16 ``` @@ -287,7 +266,6 @@ scalar int16 ### `int32` {#int32} A 32-bit integer. (`-2,147,483,648` to `2,147,483,647`) - ```typespec scalar int32 ``` @@ -297,7 +275,6 @@ scalar int32 ### `int64` {#int64} A 64-bit integer. (`-9,223,372,036,854,775,808` to `9,223,372,036,854,775,807`) - ```typespec scalar int64 ``` @@ -307,7 +284,6 @@ scalar int64 ### `int8` {#int8} A 8-bit integer. (`-128` to `127`) - ```typespec scalar int8 ``` @@ -318,7 +294,6 @@ scalar int8 A whole number. This represent any `integer` value possible. It is commonly represented as `BigInteger` in some languages. - ```typespec scalar integer ``` @@ -328,7 +303,6 @@ scalar integer ### `numeric` {#numeric} A numeric type - ```typespec scalar numeric ``` @@ -338,7 +312,6 @@ scalar numeric ### `offsetDateTime` {#offsetDateTime} A date and time in a particular time zone, e.g. "April 10th at 3:00am in PST" - ```typespec scalar offsetDateTime ``` @@ -348,7 +321,6 @@ scalar offsetDateTime ### `plainDate` {#plainDate} A date on a calendar without a time zone, e.g. "April 10th" - ```typespec scalar plainDate ``` @@ -358,7 +330,6 @@ scalar plainDate ### `plainTime` {#plainTime} A time on a clock without a time zone, e.g. "3:00 am" - ```typespec scalar plainTime ``` @@ -368,7 +339,6 @@ scalar plainTime ### `safeint` {#safeint} An integer that can be serialized to JSON (`−9007199254740991 (−(2^53 − 1))` to `9007199254740991 (2^53 − 1)` ) - ```typespec scalar safeint ``` @@ -378,7 +348,6 @@ scalar safeint ### `string` {#string} A sequence of textual characters. - ```typespec scalar string ``` @@ -388,7 +357,6 @@ scalar string ### `uint16` {#uint16} A 16-bit unsigned integer (`0` to `65,535`) - ```typespec scalar uint16 ``` @@ -398,7 +366,6 @@ scalar uint16 ### `uint32` {#uint32} A 32-bit unsigned integer (`0` to `4,294,967,295`) - ```typespec scalar uint32 ``` @@ -408,7 +375,6 @@ scalar uint32 ### `uint64` {#uint64} A 64-bit unsigned integer (`0` to `18,446,744,073,709,551,615`) - ```typespec scalar uint64 ``` @@ -418,7 +384,6 @@ scalar uint64 ### `uint8` {#uint8} A 8-bit unsigned integer (`0` to `255`) - ```typespec scalar uint8 ``` @@ -429,7 +394,6 @@ scalar uint8 Represent a 32-bit unix timestamp datetime with 1s of granularity. It measures time by the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. - ```typespec scalar unixTimestamp32 ``` @@ -439,7 +403,6 @@ scalar unixTimestamp32 ### `url` {#url} Represent a URL string as described by https://url.spec.whatwg.org/ - ```typespec scalar url ``` @@ -449,7 +412,6 @@ scalar url ### `utcDateTime` {#utcDateTime} An instant in coordinated universal time (UTC)" - ```typespec scalar utcDateTime ``` diff --git a/docs/standard-library/built-in-decorators.md b/docs/standard-library/built-in-decorators.md index badf8d098c..e7ba10b367 100644 --- a/docs/standard-library/built-in-decorators.md +++ b/docs/standard-library/built-in-decorators.md @@ -10,7 +10,6 @@ toc_max_heading_level: 3 Mark this type as deprecated. NOTE: This decorator **should not** be used, use the `#deprecated` directive instead. - ```typespec @deprecated(message: valueof string) ``` @@ -37,7 +36,6 @@ op Action(): Result; ### `@discriminator` {#@discriminator} Specify the property to be used to discriminate this type. - ```typespec @discriminator(propertyName: valueof string) ``` @@ -73,7 +71,6 @@ model Dog extends Pet {kind: "dog", bark: boolean} ### `@doc` {#@doc} Attach a documentation string. - ```typespec @doc(doc: valueof string, formatArgs?: {}) ``` @@ -99,7 +96,6 @@ model Pet {} ### `@encode` {#@encode} Specify how to encode the target type. - ```typespec @encode(encoding: string | EnumMember, encodedAs?: Scalar) ``` @@ -135,7 +131,6 @@ scalar myDateTime extends unixTimestamp; ### `@encodedName` {#@encodedName} Provide an alternative name for this type when serialized to the given mime type. - ```typespec @encodedName(mimeType: valueof string, name: valueof string) ``` @@ -172,7 +167,6 @@ expireAt: int32; ### `@error` {#@error} Specify that this model is an error type. Operations return error types when the operation has failed. - ```typespec @error ``` @@ -199,7 +193,6 @@ message: string; Attach a documentation string to describe the error return types of an operation. If an operation returns a union of success and errors it only describe the errors. See `@errorsDoc` for success documentation. - ```typespec @errorsDoc(doc: valueof string) ``` @@ -226,7 +219,6 @@ op get(): Pet | NotFound; Specify a known data format hint for this string type. For example `uuid`, `uri`, etc. This differs from the `@pattern` decorator which is meant to specify a regular expression while `@format` accepts a known format name. The format names are open ended and are left to emitter to interpret. - ```typespec @format(format: valueof string) ``` @@ -251,7 +243,6 @@ scalar uuid extends string; ### `@friendlyName` {#@friendlyName} Specifies how a templated type should name their instances. - ```typespec @friendlyName(name: valueof string, formatArgs?: unknown) ``` @@ -280,7 +271,6 @@ nextLink: string; ### `@inspectType` {#@inspectType} A debugging decorator used to inspect a type. - ```typespec @inspectType(text: valueof string) ``` @@ -299,7 +289,6 @@ A debugging decorator used to inspect a type. ### `@inspectTypeName` {#@inspectTypeName} A debugging decorator used to inspect a type name. - ```typespec @inspectTypeName(text: valueof string) ``` @@ -318,7 +307,6 @@ A debugging decorator used to inspect a type name. ### `@key` {#@key} Mark a model property as the key to identify instances of that type - ```typespec @key(altName?: valueof string) ``` @@ -344,7 +332,6 @@ model Pet { ### `@knownValues` {#@knownValues} Provide a set of known values to a string type. - ```typespec @knownValues(values: Enum) ``` @@ -374,7 +361,6 @@ Invalid, ### `@list` {#@list} Mark this operation as a `list` operation for resource types. - ```typespec @list(listedType?: Model) ``` @@ -393,7 +379,6 @@ Mark this operation as a `list` operation for resource types. ### `@maxItems` {#@maxItems} Specify the maximum number of items this array should have. - ```typespec @maxItems(value: valueof integer) ``` @@ -418,7 +403,6 @@ model Endpoints is string[]; ### `@maxLength` {#@maxLength} Specify the maximum length this string type should be. - ```typespec @maxLength(value: valueof integer) ``` @@ -443,7 +427,6 @@ scalar Username extends string; ### `@maxValue` {#@maxValue} Specify the maximum value this numeric type should be. - ```typespec @maxValue(value: valueof numeric) ``` @@ -469,7 +452,6 @@ scalar Age is int32; Specify the maximum value this numeric type should be, exclusive of the given value. - ```typespec @maxValueExclusive(value: valueof numeric) ``` @@ -494,7 +476,6 @@ scalar distance is float64; ### `@minItems` {#@minItems} Specify the minimum number of items this array should have. - ```typespec @minItems(value: valueof integer) ``` @@ -519,7 +500,6 @@ model Endpoints is string[]; ### `@minLength` {#@minLength} Specify the minimum length this string type should be. - ```typespec @minLength(value: valueof integer) ``` @@ -544,7 +524,6 @@ scalar Username extends string; ### `@minValue` {#@minValue} Specify the minimum value this numeric type should be. - ```typespec @minValue(value: valueof numeric) ``` @@ -570,7 +549,6 @@ scalar Age is int32; Specify the minimum value this numeric type should be, exclusive of the given value. - ```typespec @minValueExclusive(value: valueof numeric) ``` @@ -595,7 +573,6 @@ scalar distance is float64; ### `@overload` {#@overload} Specify this operation is an overload of the given operation. - ```typespec @overload(overloadbase: Operation) ``` @@ -623,7 +600,6 @@ op uploadBytes(data: bytes, @header contentType: "application/octet-stream"): vo ### `@parameterVisibility` {#@parameterVisibility} Sets which visibilities apply to parameters for the given operation. - ```typespec @parameterVisibility(...visibilities: valueof string[]) ``` @@ -649,7 +625,6 @@ This decorator may optionally provide a custom validation _message_. Emitters ma context when pattern validation fails. For the sake of consistency, the message should be a phrase that describes in plain language what sort of content the pattern attempts to validate. For example, a complex regular expression that validates a GUID string might have a message like "Must be a valid GUID." - ```typespec @pattern(pattern: valueof string, validationMessage?: valueof string) ``` @@ -677,7 +652,6 @@ scalar LowerAlpha extends string; DEPRECATED: Use `@encodedName` instead. Provide an alternative name for this type. - ```typespec @projectedName(targetName: valueof string, projectedName: valueof string) ``` @@ -706,7 +680,6 @@ expireAt: int32; Attach a documentation string to describe the successful return types of an operation. If an operation returns a union of success and errors it only describe the success. See `@errorsDoc` for error documentation. - ```typespec @returnsDoc(doc: valueof string) ``` @@ -731,7 +704,6 @@ op get(): Pet | NotFound; ### `@returnTypeVisibility` {#@returnTypeVisibility} Sets which visibilities apply to the return type for the given operation. - ```typespec @returnTypeVisibility(...visibilities: valueof string[]) ``` @@ -750,7 +722,6 @@ Sets which visibilities apply to the return type for the given operation. ### `@secret` {#@secret} Mark this string as a secret value that should be treated carefully to avoid exposure - ```typespec @secret ``` @@ -773,7 +744,6 @@ scalar Password is string; ### `@service` {#@service} Mark this namespace as describing a service and configure service properties. - ```typespec @service(options?: ServiceOptions) ``` @@ -812,7 +782,6 @@ namespace PetStore; ### `@summary` {#@summary} Typically a short, single-line description. - ```typespec @summary(summary: valueof string) ``` @@ -837,7 +806,6 @@ model Pet {} ### `@tag` {#@tag} Attaches a tag to an operation, interface, or namespace. Multiple `@tag` decorators can be specified to attach multiple tags to a TypeSpec element. - ```typespec @tag(tag: valueof string) ``` @@ -870,7 +838,6 @@ with standard emitters that interpret them as follows: - "delete": input to operations that delete data. See also: [Automatic visibility](https://typespec.io/docs/libraries/http/operations#automatic-visibility) - ```typespec @visibility(...visibilities: valueof string[]) ``` @@ -901,7 +868,6 @@ name: string; ### `@withDefaultKeyVisibility` {#@withDefaultKeyVisibility} Set the visibility of key properties in a model if not already set. - ```typespec @withDefaultKeyVisibility(visibility: valueof string) ``` @@ -920,7 +886,6 @@ Set the visibility of key properties in a model if not already set. ### `@withOptionalProperties` {#@withOptionalProperties} Returns the model with required properties removed. - ```typespec @withOptionalProperties ``` @@ -937,7 +902,6 @@ None ### `@withoutDefaultValues` {#@withoutDefaultValues} Returns the model with any default values removed. - ```typespec @withoutDefaultValues ``` @@ -954,7 +918,6 @@ None ### `@withoutOmittedProperties` {#@withoutOmittedProperties} Returns the model with the given properties omitted. - ```typespec @withoutOmittedProperties(omit: string | Union) ``` @@ -973,7 +936,6 @@ Returns the model with the given properties omitted. ### `@withUpdateableProperties` {#@withUpdateableProperties} Returns the model with non-updateable properties removed. - ```typespec @withUpdateableProperties ``` @@ -998,7 +960,6 @@ See also: [Automatic visibility](https://typespec.io/docs/libraries/http/operati When using an emitter that applies visibility automatically, it is generally not necessary to use this decorator. - ```typespec @withVisibility(...visibilities: valueof string[]) ``` From 5b77c53b8b1ca2b9c0b22c7e2fa67f3e6c7d1077 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 26 Feb 2024 10:49:39 -0800 Subject: [PATCH 19/24] none for no props --- packages/tspd/package.json | 1 + packages/tspd/src/ref-doc/emitters/markdown.ts | 3 +++ packages/tspd/test/emitters/markdown/model.test.ts | 12 ++++-------- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/tspd/package.json b/packages/tspd/package.json index 3b4403d027..99631cc901 100644 --- a/packages/tspd/package.json +++ b/packages/tspd/package.json @@ -44,6 +44,7 @@ "build": "tsc -p .", "watch": "tsc -p . --watch", "test": "vitest run", + "test:watch": "vitest --watch", "test:ui": "vitest --ui", "test-official": "vitest run --coverage --reporter=junit --reporter=default --no-file-parallelism", "lint": "eslint . --ext .ts --max-warnings=0", diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 9b3912478a..4be0330567 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -145,6 +145,9 @@ export class MarkdownRenderer { modelProperties(model: ModelRefDoc) { const content: MarkdownDoc = []; + if (model.properties.size === 0 && model.type.indexer === undefined) { + return section("Properties", "None"); + } const rows: { name: string; type: string; doc: string }[] = [ { name: "Name", type: "Type", doc: "Description" }, ]; diff --git a/packages/tspd/test/emitters/markdown/model.test.ts b/packages/tspd/test/emitters/markdown/model.test.ts index d97fc1c518..7cabecb726 100644 --- a/packages/tspd/test/emitters/markdown/model.test.ts +++ b/packages/tspd/test/emitters/markdown/model.test.ts @@ -23,8 +23,7 @@ it("render simple model", async () => { "", "", "## Properties", - "| Name | Type | Description |", - "|------|------|-------------|", + "None", ].join("\n") ); }); @@ -47,8 +46,7 @@ it("render model with template parameter", async () => { "", "", "## Properties", - "| Name | Type | Description |", - "|------|------|-------------|", + "None", ].join("\n") ); }); @@ -81,8 +79,7 @@ describe("model examples", () => { "```", "", "## Properties", - "| Name | Type | Description |", - "|------|------|-------------|", + "None", ].join("\n") ); }); @@ -125,8 +122,7 @@ describe("model examples", () => { "```", "", "## Properties", - "| Name | Type | Description |", - "|------|------|-------------|", + "None", ].join("\n") ); }); From 8d65194dda7c067dbe6e641120fe4286dac2cca6 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 26 Feb 2024 11:00:14 -0800 Subject: [PATCH 20/24] Better ref naming --- docs/libraries/http/reference/data-types.md | 179 +++++++++--------- docs/libraries/http/reference/decorators.md | 50 ++--- .../json-schema/reference/decorators.md | 96 +++++----- .../libraries/openapi/reference/decorators.md | 22 +-- .../openapi3/reference/decorators.md | 10 +- .../protobuf/reference/data-types.md | 11 +- .../protobuf/reference/decorators.md | 16 +- docs/libraries/rest/reference/data-types.md | 40 ++-- docs/libraries/rest/reference/decorators.md | 44 ++--- .../versioning/reference/decorators.md | 22 +-- docs/standard-library/built-in-data-types.md | 24 +-- docs/standard-library/built-in-decorators.md | 98 +++++----- packages/http/README.md | 50 ++--- packages/json-schema/README.md | 96 +++++----- packages/openapi/README.md | 22 +-- packages/openapi3/README.md | 10 +- packages/protobuf/README.md | 16 +- packages/rest/README.md | 44 ++--- .../tspd/src/ref-doc/emitters/markdown.ts | 8 +- .../tspd/test/emitters/markdown/model.test.ts | 10 + packages/versioning/README.md | 22 +-- 21 files changed, 443 insertions(+), 447 deletions(-) diff --git a/docs/libraries/http/reference/data-types.md b/docs/libraries/http/reference/data-types.md index 87c0607427..788de6ec98 100644 --- a/docs/libraries/http/reference/data-types.md +++ b/docs/libraries/http/reference/data-types.md @@ -18,9 +18,9 @@ model TypeSpec.Http.AcceptedResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 202` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `202` | The status code. | ### `ApiKeyAuth` {#TypeSpec.Http.ApiKeyAuth} @@ -57,11 +57,11 @@ model TypeSpec.Http.ApiKeyAuth #### Properties -| Name | Type | Description | -| ---- | ---------- | ----------- | -| type | `apiKey` | | -| in | `Location` | | -| name | `Name` | | +| Name | Type | Description | +| ---- | ------------------------------- | ----------- | +| type | `TypeSpec.Http.AuthType.apiKey` | | +| in | `Location` | | +| name | `Name` | | ### `AuthorizationCodeFlow` {#TypeSpec.Http.AuthorizationCodeFlow} @@ -73,13 +73,13 @@ model TypeSpec.Http.AuthorizationCodeFlow #### Properties -| Name | Type | Description | -| ---------------- | ------------------- | --------------------------------- | -| type | `authorizationCode` | authorization code flow | -| authorizationUrl | `string` | the authorization URL | -| tokenUrl | `string` | the token URL | -| refreshUrl? | `string` | the refresh URL | -| scopes | `Array` | list of scopes for the credential | +| Name | Type | Description | +| ---------------- | ------------------------------------------------ | --------------------------------- | +| type | `TypeSpec.Http.OAuth2FlowType.authorizationCode` | authorization code flow | +| authorizationUrl | `string` | the authorization URL | +| tokenUrl | `string` | the token URL | +| refreshUrl? | `string` | the refresh URL | +| scopes | `string[]` | list of scopes for the credential | ### `BadRequestResponse` {#TypeSpec.Http.BadRequestResponse} @@ -91,9 +91,9 @@ model TypeSpec.Http.BadRequestResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 400` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `400` | The status code. | ### `BasicAuth` {#TypeSpec.Http.BasicAuth} @@ -111,10 +111,10 @@ model TypeSpec.Http.BasicAuth #### Properties -| Name | Type | Description | -| ------ | ------------------ | ------------------- | -| type | `http` | Http authentication | -| scheme | `(string) "basic"` | basic auth scheme | +| Name | Type | Description | +| ------ | ----------------------------- | ------------------- | +| type | `TypeSpec.Http.AuthType.http` | Http authentication | +| scheme | `"basic"` | basic auth scheme | ### `BearerAuth` {#TypeSpec.Http.BearerAuth} @@ -132,10 +132,10 @@ model TypeSpec.Http.BearerAuth #### Properties -| Name | Type | Description | -| ------ | ------------------- | ------------------- | -| type | `http` | Http authentication | -| scheme | `(string) "bearer"` | bearer auth scheme | +| Name | Type | Description | +| ------ | ----------------------------- | ------------------- | +| type | `TypeSpec.Http.AuthType.http` | Http authentication | +| scheme | `"bearer"` | bearer auth scheme | ### `Body` {#TypeSpec.Http.Body} @@ -170,12 +170,12 @@ model TypeSpec.Http.ClientCredentialsFlow #### Properties -| Name | Type | Description | -| ----------- | ------------------- | --------------------------------- | -| type | `clientCredentials` | client credential flow | -| tokenUrl | `string` | the token URL | -| refreshUrl? | `string` | the refresh URL | -| scopes | `Array` | list of scopes for the credential | +| Name | Type | Description | +| ----------- | ------------------------------------------------ | --------------------------------- | +| type | `TypeSpec.Http.OAuth2FlowType.clientCredentials` | client credential flow | +| tokenUrl | `string` | the token URL | +| refreshUrl? | `string` | the refresh URL | +| scopes | `string[]` | list of scopes for the credential | ### `ConflictResponse` {#TypeSpec.Http.ConflictResponse} @@ -187,9 +187,9 @@ model TypeSpec.Http.ConflictResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 409` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `409` | The status code. | ### `CreatedResponse` {#TypeSpec.Http.CreatedResponse} @@ -201,9 +201,9 @@ model TypeSpec.Http.CreatedResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 201` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `201` | The status code. | ### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse} @@ -215,9 +215,9 @@ model TypeSpec.Http.ForbiddenResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 403` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `403` | The status code. | ### `HeaderOptions` {#TypeSpec.Http.HeaderOptions} @@ -229,10 +229,10 @@ model TypeSpec.Http.HeaderOptions #### Properties -| Name | Type | Description | -| ------- | --------------------------------------------------------------------------- | --------------------------------------------------------- | -| name? | `string` | Name of the header when sent over HTTP. | -| format? | `union "csv" \| "multi" \| "tsv" \| "ssv" \| "pipes" \| "simple" \| "form"` | Determines the format of the array if type array is used. | +| Name | Type | Description | +| ------- | --------------------------------------------------------------------- | --------------------------------------------------------- | +| name? | `string` | Name of the header when sent over HTTP. | +| format? | `"csv" \| "multi" \| "tsv" \| "ssv" \| "pipes" \| "simple" \| "form"` | Determines the format of the array if type array is used. | ### `ImplicitFlow` {#TypeSpec.Http.ImplicitFlow} @@ -244,12 +244,12 @@ model TypeSpec.Http.ImplicitFlow #### Properties -| Name | Type | Description | -| ---------------- | ---------- | --------------------------------- | -| type | `implicit` | implicit flow | -| authorizationUrl | `string` | the authorization URL | -| refreshUrl? | `string` | the refresh URL | -| scopes | `Array` | list of scopes for the credential | +| Name | Type | Description | +| ---------------- | --------------------------------------- | --------------------------------- | +| type | `TypeSpec.Http.OAuth2FlowType.implicit` | implicit flow | +| authorizationUrl | `string` | the authorization URL | +| refreshUrl? | `string` | the refresh URL | +| scopes | `string[]` | list of scopes for the credential | ### `LocationHeader` {#TypeSpec.Http.LocationHeader} @@ -275,10 +275,10 @@ model TypeSpec.Http.MovedResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | --------------------------------------------------------------------------------------------------- | -| statusCode | `(number) 301` | The status code. | -| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. | +| Name | Type | Description | +| ---------- | -------- | --------------------------------------------------------------------------------------------------- | +| statusCode | `301` | The status code. | +| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. | ### `NoContentResponse` {#TypeSpec.Http.NoContentResponse} @@ -290,9 +290,9 @@ model TypeSpec.Http.NoContentResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 204` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `204` | The status code. | ### `NotFoundResponse` {#TypeSpec.Http.NotFoundResponse} @@ -304,9 +304,9 @@ model TypeSpec.Http.NotFoundResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 404` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `404` | The status code. | ### `NotModifiedResponse` {#TypeSpec.Http.NotModifiedResponse} @@ -318,9 +318,9 @@ model TypeSpec.Http.NotModifiedResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 304` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `304` | The status code. | ### `OAuth2Auth` {#TypeSpec.Http.OAuth2Auth} @@ -342,10 +342,10 @@ model TypeSpec.Http.OAuth2Auth #### Properties -| Name | Type | Description | -| ----- | -------- | ----------- | -| type | `oauth2` | | -| flows | `Flows` | | +| Name | Type | Description | +| ----- | ------------------------------- | ----------- | +| type | `TypeSpec.Http.AuthType.oauth2` | | +| flows | `Flows` | | ### `OkResponse` {#TypeSpec.Http.OkResponse} @@ -357,9 +357,9 @@ model TypeSpec.Http.OkResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 200` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `200` | The status code. | ### `OpenIdConnectAuth` {#TypeSpec.Http.OpenIdConnectAuth} @@ -384,10 +384,10 @@ model TypeSpec.Http.OpenIdConnectAuth #### Properties -| Name | Type | Description | -| ---------------- | --------------- | ----------------------------------------------------------- | -| type | `openIdConnect` | Auth type | -| openIdConnectUrl | `ConnectUrl` | Connect url. It can be specified relative to the server URL | +| Name | Type | Description | +| ---------------- | -------------------------------------- | ----------------------------------------------------------- | +| type | `TypeSpec.Http.AuthType.openIdConnect` | Auth type | +| openIdConnectUrl | `ConnectUrl` | Connect url. It can be specified relative to the server URL | ### `PasswordFlow` {#TypeSpec.Http.PasswordFlow} @@ -399,12 +399,12 @@ model TypeSpec.Http.PasswordFlow #### Properties -| Name | Type | Description | -| ---------------- | ---------- | --------------------------------- | -| type | `password` | password flow | -| authorizationUrl | `string` | the authorization URL | -| refreshUrl? | `string` | the refresh URL | -| scopes | `Array` | list of scopes for the credential | +| Name | Type | Description | +| ---------------- | --------------------------------------- | --------------------------------- | +| type | `TypeSpec.Http.OAuth2FlowType.password` | password flow | +| authorizationUrl | `string` | the authorization URL | +| refreshUrl? | `string` | the refresh URL | +| scopes | `string[]` | list of scopes for the credential | ### `PlainData` {#TypeSpec.Http.PlainData} @@ -423,8 +423,7 @@ model TypeSpec.Http.PlainData #### Properties -| Name | Type | Description | -| ---- | ---- | ----------- | +None ### `QueryOptions` {#TypeSpec.Http.QueryOptions} @@ -436,10 +435,10 @@ model TypeSpec.Http.QueryOptions #### Properties -| Name | Type | Description | -| ------- | --------------------------------------------------------------------------- | --------------------------------------------------------- | -| name? | `string` | Name of the query when included in the url. | -| format? | `union "multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used. | +| Name | Type | Description | +| ------- | --------------------------------------------------------------------- | --------------------------------------------------------- | +| name? | `string` | Name of the query when included in the url. | +| format? | `"multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used. | ### `Response` {#TypeSpec.Http.Response} @@ -471,9 +470,9 @@ model TypeSpec.Http.UnauthorizedResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 401` | The status code. | +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `401` | The status code. | ### `ApiKeyLocation` {#TypeSpec.Http.ApiKeyLocation} diff --git a/docs/libraries/http/reference/decorators.md b/docs/libraries/http/reference/decorators.md index 6b095e67b3..d629ae7d2c 100644 --- a/docs/libraries/http/reference/decorators.md +++ b/docs/libraries/http/reference/decorators.md @@ -113,9 +113,9 @@ Specify this property is to be sent or received as an HTTP header. #### Parameters -| Name | Type | Description | -| ------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| headerNameOrOptions | `union string \| TypeSpec.Http.HeaderOptions` | Optional name of the header when sent over HTTP or header options.
By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`) | +| Name | Type | Description | +| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| headerNameOrOptions | `string \| TypeSpec.Http.HeaderOptions` | Optional name of the header when sent over HTTP or header options.
By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`) | #### Examples @@ -155,9 +155,9 @@ Specify if inapplicable metadata should be included in the payload for the given #### Parameters -| Name | Type | Description | -| ----- | ------------------------ | --------------------------------------------------------------- | -| value | `valueof scalar boolean` | If true, inapplicable metadata will be included in the payload. | +| Name | Type | Description | +| ----- | ----------------- | --------------------------------------------------------------- | +| value | `valueof boolean` | If true, inapplicable metadata will be included in the payload. | ### `@patch` {#@TypeSpec.Http.patch} @@ -195,9 +195,9 @@ Explicitly specify that this property is to be interpolated as a path parameter. #### Parameters -| Name | Type | Description | -| --------- | ----------------------- | --------------------------------------------------- | -| paramName | `valueof scalar string` | Optional name of the parameter in the url template. | +| Name | Type | Description | +| --------- | ---------------- | --------------------------------------------------- | +| paramName | `valueof string` | Optional name of the parameter in the url template. | #### Examples @@ -264,9 +264,9 @@ Specify this property is to be sent as a query parameter. #### Parameters -| Name | Type | Description | -| ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------- | -| queryNameOrOptions | `union string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | +| Name | Type | Description | +| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------- | +| queryNameOrOptions | `string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | #### Examples @@ -297,14 +297,14 @@ it will be used as a prefix to the route URI of the operation. #### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` #### Parameters -| Name | Type | Description | -| ------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| path | `valueof scalar string` | Relative route path. Cannot include query parameters. | -| options | `` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| Name | Type | Description | +| ------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `valueof string` | Relative route path. Cannot include query parameters. | +| options | `(anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | #### Examples @@ -327,11 +327,11 @@ Specify the endpoint for this service. #### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------------------------------------------- | -| url | `valueof scalar string` | Server endpoint | -| description | `valueof scalar string` | Description of the endpoint | -| parameters | `Record` | Optional set of parameters used to interpolate the url. | +| Name | Type | Description | +| ----------- | ----------------- | ------------------------------------------------------- | +| url | `valueof string` | Server endpoint | +| description | `valueof string` | Description of the endpoint | +| parameters | `Record` | Optional set of parameters used to interpolate the url. | #### Examples @@ -414,9 +414,9 @@ Specify this service authentication. See the [documentation in the Http library] #### Parameters -| Name | Type | Description | -| ---- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| auth | `union {} \| Union \| {}[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together) | +| Name | Type | Description | +| ---- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| auth | `{} \| Union \| {}[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together) | #### Examples diff --git a/docs/libraries/json-schema/reference/decorators.md b/docs/libraries/json-schema/reference/decorators.md index 39d7069aa0..a61dd90562 100644 --- a/docs/libraries/json-schema/reference/decorators.md +++ b/docs/libraries/json-schema/reference/decorators.md @@ -22,9 +22,9 @@ Set the base URI for any schemas emitted from types within this namespace. #### Parameters -| Name | Type | Description | -| ------- | ----------------------- | ------------------------------------------------------------------------ | -| baseUri | `valueof scalar string` | the base URI. Schema IDs inside this namespace are relative to this URI. | +| Name | Type | Description | +| ------- | ---------------- | ------------------------------------------------------------------------ | +| baseUri | `valueof string` | the base URI. Schema IDs inside this namespace are relative to this URI. | ### `@contains` {#@TypeSpec.JsonSchema.contains} @@ -37,7 +37,7 @@ Use `@minContains` and `@maxContains` to customize how many instances to expect. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters @@ -55,13 +55,13 @@ Specify the encoding used for the contents of a string. #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------- | -| value | `valueof scalar string` |
| +| Name | Type | Description | +| ----- | ---------------- | ----------- | +| value | `valueof string` |
| ### `@contentMediaType` {#@TypeSpec.JsonSchema.contentMediaType} @@ -73,13 +73,13 @@ Specify the content type of content stored in a string. #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------- | -| value | `valueof scalar string` | the media type of the string contents | +| Name | Type | Description | +| ----- | ---------------- | ------------------------------------- | +| value | `valueof string` | the media type of the string contents | ### `@contentSchema` {#@TypeSpec.JsonSchema.contentSchema} @@ -92,7 +92,7 @@ media type and encoding. #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters @@ -118,10 +118,10 @@ emit the raw JSON code `{x: "value"}`. #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | --------------------------------------------------------------------------------------- | -| key | `valueof scalar string` | the name of the keyword of vendor extension, e.g. `x-custom`. | -| value | `unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | +| Name | Type | Description | +| ----- | ---------------- | --------------------------------------------------------------------------------------- | +| key | `valueof string` | the name of the keyword of vendor extension, e.g. `x-custom`. | +| value | `unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | ### `@id` {#@TypeSpec.JsonSchema.id} @@ -140,9 +140,9 @@ By default, the id will be constructed based on the declaration's name. #### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ----------------------------------------------- | -| id | `valueof scalar string` | the id of the JSON schema for this declaration. | +| Name | Type | Description | +| ---- | ---------------- | ----------------------------------------------- | +| id | `valueof string` | the id of the JSON schema for this declaration. | ### `@jsonSchema` {#@TypeSpec.JsonSchema.jsonSchema} @@ -162,9 +162,9 @@ you can provide the id. #### Parameters -| Name | Type | Description | -| ------- | ----------------------- | --------------------------------------------------- | -| baseUri | `valueof scalar string` | Schema IDs are interpreted as relative to this URI. | +| Name | Type | Description | +| ------- | ---------------- | --------------------------------------------------- | +| baseUri | `valueof string` | Schema IDs are interpreted as relative to this URI. | ### `@maxContains` {#@TypeSpec.JsonSchema.maxContains} @@ -177,13 +177,13 @@ by the contains decorator. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The maximum number of instances the array must contain | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The maximum number of instances the array must contain | ### `@maxProperties` {#@TypeSpec.JsonSchema.maxProperties} @@ -195,13 +195,13 @@ Specify the maximum number of properties this object can have. #### Target -`union Record | ModelProperty` +`Record | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The maximum number of properties this object can have. | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The maximum number of properties this object can have. | ### `@minContains` {#@TypeSpec.JsonSchema.minContains} @@ -214,13 +214,13 @@ by the contains decorator. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The minimum number of instances the array must contain | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The minimum number of instances the array must contain | ### `@minProperties` {#@TypeSpec.JsonSchema.minProperties} @@ -232,13 +232,13 @@ Specify the minimum number of properties this object can have. #### Target -`union Record | ModelProperty` +`Record | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The minimum number of properties this object can have. | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The minimum number of properties this object can have. | ### `@multipleOf` {#@TypeSpec.JsonSchema.multipleOf} @@ -250,13 +250,13 @@ Specify that the numeric type must be a multiple of some numeric value. #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ------------------------ | -------------------------------------------------- | -| value | `valueof scalar numeric` | The numeric type must be a multiple of this value. | +| Name | Type | Description | +| ----- | ----------------- | -------------------------------------------------- | +| value | `valueof numeric` | The numeric type must be a multiple of this value. | ### `@prefixItems` {#@TypeSpec.JsonSchema.prefixItems} @@ -268,13 +268,13 @@ Specify that the target array must begin with the provided types. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ------- | --------------------------------------------------------------------------- | -| value | `Array` | a tuple containing the types that must be present at the start of the array | +| Name | Type | Description | +| ----- | ----------- | --------------------------------------------------------------------------- | +| value | `unknown[]` | a tuple containing the types that must be present at the start of the array | ### `@uniqueItems` {#@TypeSpec.JsonSchema.uniqueItems} @@ -286,7 +286,7 @@ Specify that every item in the array must be unique. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters diff --git a/docs/libraries/openapi/reference/decorators.md b/docs/libraries/openapi/reference/decorators.md index 47fbb964c1..90b23016bb 100644 --- a/docs/libraries/openapi/reference/decorators.md +++ b/docs/libraries/openapi/reference/decorators.md @@ -48,10 +48,10 @@ Attach some custom data to the OpenAPI element generated from this type. #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------------------------------- | -| key | `valueof scalar string` | Extension key. Must start with `x-` | -| value | `unknown` | Extension value. | +| Name | Type | Description | +| ----- | ---------------- | ----------------------------------- | +| key | `valueof string` | Extension key. Must start with `x-` | +| value | `unknown` | Extension value. | #### Examples @@ -80,10 +80,10 @@ Specify the OpenAPI `externalDocs` property for this type. #### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ----------------------- | -| url | `valueof scalar string` | Url to the docs | -| description | `valueof scalar string` | Description of the docs | +| Name | Type | Description | +| ----------- | ---------------- | ----------------------- | +| url | `valueof string` | Url to the docs | +| description | `valueof string` | Description of the docs | #### Examples @@ -128,9 +128,9 @@ Specify the OpenAPI `operationId` property for this operation. #### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------- | -| operationId | `valueof scalar string` | Operation id value. | +| Name | Type | Description | +| ----------- | ---------------- | ------------------- | +| operationId | `valueof string` | Operation id value. | #### Examples diff --git a/docs/libraries/openapi3/reference/decorators.md b/docs/libraries/openapi3/reference/decorators.md index eefd6469cc..c377176b73 100644 --- a/docs/libraries/openapi3/reference/decorators.md +++ b/docs/libraries/openapi3/reference/decorators.md @@ -18,7 +18,7 @@ Specify that `oneOf` should be used instead of `anyOf` for that union. #### Target -`union Union | ModelProperty` +`Union | ModelProperty` #### Parameters @@ -34,10 +34,10 @@ Specify an external reference that should be used inside of emitting this type. #### Target -`union Model | ModelProperty` +`Model | ModelProperty` #### Parameters -| Name | Type | Description | -| ---- | ----------------------- | -------------------------------------------------------------------- | -| ref | `valueof scalar string` | External reference(e.g. "../../common.json#/components/schemas/Foo") | +| Name | Type | Description | +| ---- | ---------------- | -------------------------------------------------------------------- | +| ref | `valueof string` | External reference(e.g. "../../common.json#/components/schemas/Foo") | diff --git a/docs/libraries/protobuf/reference/data-types.md b/docs/libraries/protobuf/reference/data-types.md index ec981dc207..846a8b5c55 100644 --- a/docs/libraries/protobuf/reference/data-types.md +++ b/docs/libraries/protobuf/reference/data-types.md @@ -67,8 +67,7 @@ model TypeSpec.Protobuf.Map #### Properties -| Name | Type | Description | -| ---- | ---- | ----------- | +None ### `PackageDetails` {#TypeSpec.Protobuf.PackageDetails} @@ -80,10 +79,10 @@ model TypeSpec.Protobuf.PackageDetails #### Properties -| Name | Type | Description | -| -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| name? | `string` | The package's name.

By default, the package's name is constructed from the namespace it is applied to. | -| options? | `Record` | The package's top-level options.

See the [Protobuf Language Guide - Options](https://protobuf.dev/programming-guides/proto3/#options) for more information.

Currently, only string, boolean, and numeric options are supported. | +| Name | Type | Description | +| -------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name? | `string` | The package's name.

By default, the package's name is constructed from the namespace it is applied to. | +| options? | `Record` | The package's top-level options.

See the [Protobuf Language Guide - Options](https://protobuf.dev/programming-guides/proto3/#options) for more information.

Currently, only string, boolean, and numeric options are supported. | ### `StreamMode` {#TypeSpec.Protobuf.StreamMode} diff --git a/docs/libraries/protobuf/reference/decorators.md b/docs/libraries/protobuf/reference/decorators.md index 3a16ef5385..1491b78bf6 100644 --- a/docs/libraries/protobuf/reference/decorators.md +++ b/docs/libraries/protobuf/reference/decorators.md @@ -29,9 +29,9 @@ The field index of a Protobuf message must: #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------ | -| index | `valueof scalar uint32` | The whole-number index of the field. | +| Name | Type | Description | +| ----- | ---------------- | ------------------------------------ | +| index | `valueof uint32` | The whole-number index of the field. | #### Examples @@ -59,7 +59,7 @@ This decorator will force the emitter to check and emit a model. #### Target -`` +`{}` #### Parameters @@ -113,13 +113,13 @@ information. #### Target -`` +`{}` #### Parameters -| Name | Type | Description | -| ------------ | ------------------------------------------------------ | ---------------------------- | -| reservations | `valueof model string \| [uint32, uint32] \| uint32[]` | a list of field reservations | +| Name | Type | Description | +| ------------ | ------------------------------------------------ | ---------------------------- | +| reservations | `valueof string \| [uint32, uint32] \| uint32[]` | a list of field reservations | #### Examples diff --git a/docs/libraries/rest/reference/data-types.md b/docs/libraries/rest/reference/data-types.md index 7f03e5d814..6b1dcd5d1e 100644 --- a/docs/libraries/rest/reference/data-types.md +++ b/docs/libraries/rest/reference/data-types.md @@ -37,10 +37,10 @@ model TypeSpec.Rest.Resource.CollectionWithNextLink #### Properties -| Name | Type | Description | -| --------- | ------------------ | ----------- | -| value | `Array` | | -| nextLink? | `ResourceLocation` | | +| Name | Type | Description | +| --------- | -------------------------------- | ----------- | +| value | `Array` | | +| nextLink? | `TypeSpec.Rest.ResourceLocation` | | ### `KeysOf` {#TypeSpec.Rest.Resource.KeysOf} @@ -58,8 +58,7 @@ model TypeSpec.Rest.Resource.KeysOf #### Properties -| Name | Type | Description | -| ---- | ---- | ----------- | +None ### `ParentKeysOf` {#TypeSpec.Rest.Resource.ParentKeysOf} @@ -77,8 +76,7 @@ model TypeSpec.Rest.Resource.ParentKeysOf #### Properties -| Name | Type | Description | -| ---- | ---- | ----------- | +None ### `ResourceCollectionParameters` {#TypeSpec.Rest.Resource.ResourceCollectionParameters} @@ -96,8 +94,7 @@ model TypeSpec.Rest.Resource.ResourceCollectionParameters #### Properties -| Name | Type | Description | -| ---- | ---- | ----------- | +None ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} @@ -115,10 +112,10 @@ model TypeSpec.Rest.Resource.ResourceCreatedResponse #### Properties -| Name | Type | Description | -| ---------- | -------------- | ---------------- | -| statusCode | `(number) 201` | The status code. | -| body | `Resource` | | +| Name | Type | Description | +| ---------- | ---------- | ---------------- | +| statusCode | `201` | The status code. | +| body | `Resource` | | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} @@ -136,8 +133,7 @@ model TypeSpec.Rest.Resource.ResourceCreateModel #### Properties -| Name | Type | Description | -| ---- | ---- | ----------- | +None ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} @@ -155,8 +151,7 @@ model TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel #### Properties -| Name | Type | Description | -| ---- | ---- | ----------- | +None ### `ResourceDeletedResponse` {#TypeSpec.Rest.Resource.ResourceDeletedResponse} @@ -168,9 +163,9 @@ model TypeSpec.Rest.Resource.ResourceDeletedResponse #### Properties -| Name | Type | Description | -| ---- | -------------- | ---------------- | -| \_ | `(number) 200` | The status code. | +| Name | Type | Description | +| ---- | ----- | ---------------- | +| \_ | `200` | The status code. | ### `ResourceError` {#TypeSpec.Rest.Resource.ResourceError} @@ -203,5 +198,4 @@ model TypeSpec.Rest.Resource.ResourceParameters #### Properties -| Name | Type | Description | -| ---- | ---- | ----------- | +None diff --git a/docs/libraries/rest/reference/decorators.md b/docs/libraries/rest/reference/decorators.md index cccfb86be3..39ec842b5a 100644 --- a/docs/libraries/rest/reference/decorators.md +++ b/docs/libraries/rest/reference/decorators.md @@ -22,9 +22,9 @@ Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my #### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ----------------------------------------------------------------------------- | -| name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. | +| Name | Type | Description | +| ---- | ---------------- | ----------------------------------------------------------------------------- | +| name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | ### `@actionSeparator` {#@TypeSpec.Rest.actionSeparator} @@ -36,13 +36,13 @@ Defines the separator string that is inserted before the action name in auto-gen #### Target -`union Model | ModelProperty | Operation` +`Model | ModelProperty | Operation` #### Parameters -| Name | Type | Description | -| --------- | ---------------------------------- | ---------------------------------------------------------------- | -| seperator | `valueof union "/" \| ":" \| "/:"` | Seperator seperating the action segment from the rest of the url | +| Name | Type | Description | +| --------- | ---------------------------- | ---------------------------------------------------------------- | +| seperator | `valueof "/" \| ":" \| "/:"` | Seperator seperating the action segment from the rest of the url | ### `@autoRoute` {#@TypeSpec.Rest.autoRoute} @@ -54,7 +54,7 @@ This interface or operation should resolve its route automatically. To be used w #### Target -`union Interface | Operation` +`Interface | Operation` #### Parameters @@ -83,10 +83,10 @@ Specify this operation is a collection action. (Scopped to a resource, /pets/my- #### Parameters -| Name | Type | Description | -| ------------ | ----------------------- | ----------------------------------------------------------------------------- | -| resourceType | `Model` | Resource marked with | -| name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. | +| Name | Type | Description | +| ------------ | ---------------- | ----------------------------------------------------------------------------- | +| resourceType | `Model` | Resource marked with | +| name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | ### `@copyResourceKeyParameters` {#@TypeSpec.Rest.copyResourceKeyParameters} @@ -102,9 +102,9 @@ Copy the resource key parameters on the model #### Parameters -| Name | Type | Description | -| ------ | ----------------------- | ------------------------------------- | -| filter | `valueof scalar string` | Filter to exclude certain properties. | +| Name | Type | Description | +| ------ | ---------------- | ------------------------------------- | +| filter | `valueof string` | Filter to exclude certain properties. | ### `@createsOrReplacesResource` {#@TypeSpec.Rest.createsOrReplacesResource} @@ -246,9 +246,9 @@ Mark this model as a resource type with a name. #### Parameters -| Name | Type | Description | -| -------------- | ----------------------- | ---------------------- | -| collectionName | `valueof scalar string` | type's collection name | +| Name | Type | Description | +| -------------- | ---------------- | ---------------------- | +| collectionName | `valueof string` | type's collection name | ### `@segment` {#@TypeSpec.Rest.segment} @@ -260,13 +260,13 @@ Defines the preceding path segment for a #### Target -`union Model | ModelProperty | Operation` +`Model | ModelProperty | Operation` #### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ---------------------------------------------------------------------------------------------- | -| name | `valueof scalar string` | Segment that will be inserted into the operation route before the path parameter's name field. | +| Name | Type | Description | +| ---- | ---------------- | ---------------------------------------------------------------------------------------------- | +| name | `valueof string` | Segment that will be inserted into the operation route before the path parameter's name field. | #### Examples diff --git a/docs/libraries/versioning/reference/decorators.md b/docs/libraries/versioning/reference/decorators.md index 871efc731e..08da695b58 100644 --- a/docs/libraries/versioning/reference/decorators.md +++ b/docs/libraries/versioning/reference/decorators.md @@ -18,7 +18,7 @@ Identifies when the target was added. #### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` #### Parameters @@ -82,7 +82,7 @@ Identifies when the target was removed. #### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` #### Parameters @@ -117,14 +117,14 @@ Identifies when the target has been renamed. #### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` #### Parameters -| Name | Type | Description | -| ------- | ----------------------- | ------------------------------------------- | -| version | `EnumMember` | The version that the target was renamed in. | -| oldName | `valueof scalar string` | The previous name of the target. | +| Name | Type | Description | +| ------- | ---------------- | ------------------------------------------- | +| version | `EnumMember` | The version that the target was renamed in. | +| oldName | `valueof string` | The previous name of the target. | #### Examples @@ -181,13 +181,13 @@ Identifies that a namespace or a given versioning enum member relies upon a vers #### Target -`union EnumMember | Namespace` +`EnumMember | Namespace` #### Parameters -| Name | Type | Description | -| -------------- | ------- | --------------------------------------------------------------------- | -| versionRecords | `Array` | The dependent library version(s) for the target namespace or version. | +| Name | Type | Description | +| -------------- | -------------- | --------------------------------------------------------------------- | +| versionRecords | `EnumMember[]` | The dependent library version(s) for the target namespace or version. | #### Examples diff --git a/docs/standard-library/built-in-data-types.md b/docs/standard-library/built-in-data-types.md index e6ff74a9a7..719158cd91 100644 --- a/docs/standard-library/built-in-data-types.md +++ b/docs/standard-library/built-in-data-types.md @@ -20,8 +20,7 @@ model Array #### Properties -| Name | Type | Description | -|------|------|-------------| +None ### `DefaultKeyVisibility` {#DefaultKeyVisibility} @@ -38,8 +37,7 @@ model DefaultKeyVisibility #### Properties -| Name | Type | Description | -|------|------|-------------| +None ### `object` {#object} @@ -50,8 +48,7 @@ model object #### Properties -| Name | Type | Description | -|------|------|-------------| +None ### `OmitDefaults` {#OmitDefaults} @@ -67,8 +64,7 @@ model OmitDefaults #### Properties -| Name | Type | Description | -|------|------|-------------| +None ### `OmitProperties` {#OmitProperties} @@ -85,8 +81,7 @@ model OmitProperties #### Properties -| Name | Type | Description | -|------|------|-------------| +None ### `OptionalProperties` {#OptionalProperties} @@ -102,8 +97,7 @@ model OptionalProperties #### Properties -| Name | Type | Description | -|------|------|-------------| +None ### `Record` {#Record} @@ -120,8 +114,7 @@ model Record #### Properties -| Name | Type | Description | -|------|------|-------------| +None ### `ServiceOptions` {#ServiceOptions} @@ -151,8 +144,7 @@ model UpdateableProperties #### Properties -| Name | Type | Description | -|------|------|-------------| +None ### `BytesKnownEncoding` {#BytesKnownEncoding} diff --git a/docs/standard-library/built-in-decorators.md b/docs/standard-library/built-in-decorators.md index e7ba10b367..fe3cf11a22 100644 --- a/docs/standard-library/built-in-decorators.md +++ b/docs/standard-library/built-in-decorators.md @@ -21,7 +21,7 @@ NOTE: This decorator **should not** be used, use the `#deprecated` directive ins #### Parameters | Name | Type | Description | |------|------|-------------| -| message | `valueof scalar string` | Deprecation message. | +| message | `valueof string` | Deprecation message. | #### Examples @@ -42,12 +42,12 @@ Specify the property to be used to discriminate this type. #### Target -`union Model | Union` +`Model | Union` #### Parameters | Name | Type | Description | |------|------|-------------| -| propertyName | `valueof scalar string` | The property name to use for discrimination | +| propertyName | `valueof string` | The property name to use for discrimination | #### Examples @@ -82,8 +82,8 @@ Attach a documentation string. #### Parameters | Name | Type | Description | |------|------|-------------| -| doc | `valueof scalar string` | Documentation string | -| formatArgs | `` | Record with key value pair that can be interpolated in the doc. | +| doc | `valueof string` | Documentation string | +| formatArgs | `{}` | Record with key value pair that can be interpolated in the doc. | #### Examples @@ -102,12 +102,12 @@ Specify how to encode the target type. #### Target -`union Scalar | ModelProperty` +`Scalar | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| encoding | `union string \| EnumMember` | Known name of an encoding. | +| encoding | `string \| EnumMember` | Known name of an encoding. | | encodedAs | `Scalar` | What target type is this being encoded as. Default to string. | #### Examples @@ -142,8 +142,8 @@ Provide an alternative name for this type when serialized to the given mime type #### Parameters | Name | Type | Description | |------|------|-------------| -| mimeType | `valueof scalar string` | Mime type this should apply to. The mime type should be a known mime type as described here https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types without any suffix (e.g. `+json`) | -| name | `valueof scalar string` | Alternative name | +| mimeType | `valueof string` | Mime type this should apply to. The mime type should be a known mime type as described here https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types without any suffix (e.g. `+json`) | +| name | `valueof string` | Alternative name | #### Examples @@ -204,7 +204,7 @@ If an operation returns a union of success and errors it only describe the error #### Parameters | Name | Type | Description | |------|------|-------------| -| doc | `valueof scalar string` | Documentation string | +| doc | `valueof string` | Documentation string | #### Examples @@ -225,12 +225,12 @@ The format names are open ended and are left to emitter to interpret. #### Target -`union string | bytes | ModelProperty` +`string | bytes | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| format | `valueof scalar string` | format name. | +| format | `valueof string` | format name. | #### Examples @@ -254,7 +254,7 @@ Specifies how a templated type should name their instances. #### Parameters | Name | Type | Description | |------|------|-------------| -| name | `valueof scalar string` | name the template instance should take | +| name | `valueof string` | name the template instance should take | | formatArgs | `unknown` | Model with key value used to interpolate the name | #### Examples @@ -282,7 +282,7 @@ A debugging decorator used to inspect a type. #### Parameters | Name | Type | Description | |------|------|-------------| -| text | `valueof scalar string` | Custom text to log | +| text | `valueof string` | Custom text to log | @@ -300,7 +300,7 @@ A debugging decorator used to inspect a type name. #### Parameters | Name | Type | Description | |------|------|-------------| -| text | `valueof scalar string` | Custom text to log | +| text | `valueof string` | Custom text to log | @@ -318,7 +318,7 @@ Mark a model property as the key to identify instances of that type #### Parameters | Name | Type | Description | |------|------|-------------| -| altName | `valueof scalar string` | Name of the property. If not specified, the decorated property name is used. | +| altName | `valueof string` | Name of the property. If not specified, the decorated property name is used. | #### Examples @@ -338,7 +338,7 @@ Provide a set of known values to a string type. #### Target -`union string | numeric | ModelProperty` +`string | numeric | ModelProperty` #### Parameters | Name | Type | Description | @@ -385,12 +385,12 @@ Specify the maximum number of items this array should have. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar integer` | Maximum number | +| value | `valueof integer` | Maximum number | #### Examples @@ -409,12 +409,12 @@ Specify the maximum length this string type should be. #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar integer` | Maximum length | +| value | `valueof integer` | Maximum length | #### Examples @@ -433,12 +433,12 @@ Specify the maximum value this numeric type should be. #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar numeric` | Maximum value | +| value | `valueof numeric` | Maximum value | #### Examples @@ -458,12 +458,12 @@ value. #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar numeric` | Maximum value | +| value | `valueof numeric` | Maximum value | #### Examples @@ -482,12 +482,12 @@ Specify the minimum number of items this array should have. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar integer` | Minimum number | +| value | `valueof integer` | Minimum number | #### Examples @@ -506,12 +506,12 @@ Specify the minimum length this string type should be. #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar integer` | Minimum length | +| value | `valueof integer` | Minimum length | #### Examples @@ -530,12 +530,12 @@ Specify the minimum value this numeric type should be. #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar numeric` | Minimum value | +| value | `valueof numeric` | Minimum value | #### Examples @@ -555,12 +555,12 @@ value. #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar numeric` | Minimum value | +| value | `valueof numeric` | Minimum value | #### Examples @@ -611,7 +611,7 @@ Sets which visibilities apply to parameters for the given operation. #### Parameters | Name | Type | Description | |------|------|-------------| -| visibilities | `valueof model string[]` | List of visibility strings which apply to this operation. | +| visibilities | `valueof string[]` | List of visibility strings which apply to this operation. | @@ -631,13 +631,13 @@ validates a GUID string might have a message like "Must be a valid GUID." #### Target -`union string | bytes | ModelProperty` +`string | bytes | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| pattern | `valueof scalar string` | Regular expression. | -| validationMessage | `valueof scalar string` | Optional validation message that may provide context when validation fails. | +| pattern | `valueof string` | Regular expression. | +| validationMessage | `valueof string` | Optional validation message that may provide context when validation fails. | #### Examples @@ -663,8 +663,8 @@ Provide an alternative name for this type. #### Parameters | Name | Type | Description | |------|------|-------------| -| targetName | `valueof scalar string` | Projection target | -| projectedName | `valueof scalar string` | Alternative name | +| targetName | `valueof string` | Projection target | +| projectedName | `valueof string` | Alternative name | #### Examples @@ -691,7 +691,7 @@ If an operation returns a union of success and errors it only describe the succe #### Parameters | Name | Type | Description | |------|------|-------------| -| doc | `valueof scalar string` | Documentation string | +| doc | `valueof string` | Documentation string | #### Examples @@ -715,7 +715,7 @@ Sets which visibilities apply to the return type for the given operation. #### Parameters | Name | Type | Description | |------|------|-------------| -| visibilities | `valueof model string[]` | List of visibility strings which apply to this operation. | +| visibilities | `valueof string[]` | List of visibility strings which apply to this operation. | @@ -728,7 +728,7 @@ Mark this string as a secret value that should be treated carefully to avoid exp #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters None @@ -793,7 +793,7 @@ Typically a short, single-line description. #### Parameters | Name | Type | Description | |------|------|-------------| -| summary | `valueof scalar string` | Summary string. | +| summary | `valueof string` | Summary string. | #### Examples @@ -812,12 +812,12 @@ Attaches a tag to an operation, interface, or namespace. Multiple `@tag` decorat #### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` #### Parameters | Name | Type | Description | |------|------|-------------| -| tag | `valueof scalar string` | Tag value | +| tag | `valueof string` | Tag value | @@ -849,7 +849,7 @@ See also: [Automatic visibility](https://typespec.io/docs/libraries/http/operati #### Parameters | Name | Type | Description | |------|------|-------------| -| visibilities | `valueof model string[]` | List of visibilities which apply to this property. | +| visibilities | `valueof string[]` | List of visibilities which apply to this property. | #### Examples @@ -879,7 +879,7 @@ Set the visibility of key properties in a model if not already set. #### Parameters | Name | Type | Description | |------|------|-------------| -| visibility | `valueof scalar string` | The desired default visibility value. If a key property already has a `visibility` decorator then the default visibility is not applied. | +| visibility | `valueof string` | The desired default visibility value. If a key property already has a `visibility` decorator then the default visibility is not applied. | @@ -929,7 +929,7 @@ Returns the model with the given properties omitted. #### Parameters | Name | Type | Description | |------|------|-------------| -| omit | `union string \| Union` | List of properties to omit | +| omit | `string \| Union` | List of properties to omit | @@ -971,7 +971,7 @@ not necessary to use this decorator. #### Parameters | Name | Type | Description | |------|------|-------------| -| visibilities | `valueof model string[]` | List of visibilities which apply to this property. | +| visibilities | `valueof string[]` | List of visibilities which apply to this property. | #### Examples diff --git a/packages/http/README.md b/packages/http/README.md index 4c028f6b17..73f1fb9ffa 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -158,9 +158,9 @@ Specify this property is to be sent or received as an HTTP header. ##### Parameters -| Name | Type | Description | -| ------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| headerNameOrOptions | `union string \| TypeSpec.Http.HeaderOptions` | Optional name of the header when sent over HTTP or header options.
By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`) | +| Name | Type | Description | +| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| headerNameOrOptions | `string \| TypeSpec.Http.HeaderOptions` | Optional name of the header when sent over HTTP or header options.
By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`) | ##### Examples @@ -200,9 +200,9 @@ Specify if inapplicable metadata should be included in the payload for the given ##### Parameters -| Name | Type | Description | -| ----- | ------------------------ | --------------------------------------------------------------- | -| value | `valueof scalar boolean` | If true, inapplicable metadata will be included in the payload. | +| Name | Type | Description | +| ----- | ----------------- | --------------------------------------------------------------- | +| value | `valueof boolean` | If true, inapplicable metadata will be included in the payload. | #### `@patch` @@ -240,9 +240,9 @@ Explicitly specify that this property is to be interpolated as a path parameter. ##### Parameters -| Name | Type | Description | -| --------- | ----------------------- | --------------------------------------------------- | -| paramName | `valueof scalar string` | Optional name of the parameter in the url template. | +| Name | Type | Description | +| --------- | ---------------- | --------------------------------------------------- | +| paramName | `valueof string` | Optional name of the parameter in the url template. | ##### Examples @@ -309,9 +309,9 @@ Specify this property is to be sent as a query parameter. ##### Parameters -| Name | Type | Description | -| ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------- | -| queryNameOrOptions | `union string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | +| Name | Type | Description | +| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------- | +| queryNameOrOptions | `string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | ##### Examples @@ -342,14 +342,14 @@ it will be used as a prefix to the route URI of the operation. ##### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` ##### Parameters -| Name | Type | Description | -| ------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| path | `valueof scalar string` | Relative route path. Cannot include query parameters. | -| options | `` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| Name | Type | Description | +| ------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `valueof string` | Relative route path. Cannot include query parameters. | +| options | `(anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | ##### Examples @@ -372,11 +372,11 @@ Specify the endpoint for this service. ##### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------------------------------------------- | -| url | `valueof scalar string` | Server endpoint | -| description | `valueof scalar string` | Description of the endpoint | -| parameters | `Record` | Optional set of parameters used to interpolate the url. | +| Name | Type | Description | +| ----------- | ----------------- | ------------------------------------------------------- | +| url | `valueof string` | Server endpoint | +| description | `valueof string` | Description of the endpoint | +| parameters | `Record` | Optional set of parameters used to interpolate the url. | ##### Examples @@ -459,9 +459,9 @@ Specify this service authentication. See the [documentation in the Http library] ##### Parameters -| Name | Type | Description | -| ---- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| auth | `union {} \| Union \| {}[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together) | +| Name | Type | Description | +| ---- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| auth | `{} \| Union \| {}[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together) | ##### Examples diff --git a/packages/json-schema/README.md b/packages/json-schema/README.md index 6eba82661b..9abdc9d89e 100644 --- a/packages/json-schema/README.md +++ b/packages/json-schema/README.md @@ -112,9 +112,9 @@ Set the base URI for any schemas emitted from types within this namespace. ##### Parameters -| Name | Type | Description | -| ------- | ----------------------- | ------------------------------------------------------------------------ | -| baseUri | `valueof scalar string` | the base URI. Schema IDs inside this namespace are relative to this URI. | +| Name | Type | Description | +| ------- | ---------------- | ------------------------------------------------------------------------ | +| baseUri | `valueof string` | the base URI. Schema IDs inside this namespace are relative to this URI. | #### `@contains` @@ -127,7 +127,7 @@ Use `@minContains` and `@maxContains` to customize how many instances to expect. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters @@ -145,13 +145,13 @@ Specify the encoding used for the contents of a string. ##### Target -`union string | ModelProperty` +`string | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------- | -| value | `valueof scalar string` |
| +| Name | Type | Description | +| ----- | ---------------- | ----------- | +| value | `valueof string` |
| #### `@contentMediaType` @@ -163,13 +163,13 @@ Specify the content type of content stored in a string. ##### Target -`union string | ModelProperty` +`string | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------- | -| value | `valueof scalar string` | the media type of the string contents | +| Name | Type | Description | +| ----- | ---------------- | ------------------------------------- | +| value | `valueof string` | the media type of the string contents | #### `@contentSchema` @@ -182,7 +182,7 @@ media type and encoding. ##### Target -`union string | ModelProperty` +`string | ModelProperty` ##### Parameters @@ -208,10 +208,10 @@ emit the raw JSON code `{x: "value"}`. ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | --------------------------------------------------------------------------------------- | -| key | `valueof scalar string` | the name of the keyword of vendor extension, e.g. `x-custom`. | -| value | `unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | +| Name | Type | Description | +| ----- | ---------------- | --------------------------------------------------------------------------------------- | +| key | `valueof string` | the name of the keyword of vendor extension, e.g. `x-custom`. | +| value | `unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | #### `@id` @@ -230,9 +230,9 @@ By default, the id will be constructed based on the declaration's name. ##### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ----------------------------------------------- | -| id | `valueof scalar string` | the id of the JSON schema for this declaration. | +| Name | Type | Description | +| ---- | ---------------- | ----------------------------------------------- | +| id | `valueof string` | the id of the JSON schema for this declaration. | #### `@jsonSchema` @@ -252,9 +252,9 @@ you can provide the id. ##### Parameters -| Name | Type | Description | -| ------- | ----------------------- | --------------------------------------------------- | -| baseUri | `valueof scalar string` | Schema IDs are interpreted as relative to this URI. | +| Name | Type | Description | +| ------- | ---------------- | --------------------------------------------------- | +| baseUri | `valueof string` | Schema IDs are interpreted as relative to this URI. | #### `@maxContains` @@ -267,13 +267,13 @@ by the contains decorator. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The maximum number of instances the array must contain | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The maximum number of instances the array must contain | #### `@maxProperties` @@ -285,13 +285,13 @@ Specify the maximum number of properties this object can have. ##### Target -`union Record | ModelProperty` +`Record | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The maximum number of properties this object can have. | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The maximum number of properties this object can have. | #### `@minContains` @@ -304,13 +304,13 @@ by the contains decorator. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The minimum number of instances the array must contain | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The minimum number of instances the array must contain | #### `@minProperties` @@ -322,13 +322,13 @@ Specify the minimum number of properties this object can have. ##### Target -`union Record | ModelProperty` +`Record | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The minimum number of properties this object can have. | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The minimum number of properties this object can have. | #### `@multipleOf` @@ -340,13 +340,13 @@ Specify that the numeric type must be a multiple of some numeric value. ##### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ------------------------ | -------------------------------------------------- | -| value | `valueof scalar numeric` | The numeric type must be a multiple of this value. | +| Name | Type | Description | +| ----- | ----------------- | -------------------------------------------------- | +| value | `valueof numeric` | The numeric type must be a multiple of this value. | #### `@prefixItems` @@ -358,13 +358,13 @@ Specify that the target array must begin with the provided types. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ------- | --------------------------------------------------------------------------- | -| value | `Array` | a tuple containing the types that must be present at the start of the array | +| Name | Type | Description | +| ----- | ----------- | --------------------------------------------------------------------------- | +| value | `unknown[]` | a tuple containing the types that must be present at the start of the array | #### `@uniqueItems` @@ -376,7 +376,7 @@ Specify that every item in the array must be unique. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters diff --git a/packages/openapi/README.md b/packages/openapi/README.md index 202f8d8e29..3e5a84e4b0 100644 --- a/packages/openapi/README.md +++ b/packages/openapi/README.md @@ -58,10 +58,10 @@ Attach some custom data to the OpenAPI element generated from this type. ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------------------------------- | -| key | `valueof scalar string` | Extension key. Must start with `x-` | -| value | `unknown` | Extension value. | +| Name | Type | Description | +| ----- | ---------------- | ----------------------------------- | +| key | `valueof string` | Extension key. Must start with `x-` | +| value | `unknown` | Extension value. | ##### Examples @@ -90,10 +90,10 @@ Specify the OpenAPI `externalDocs` property for this type. ##### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ----------------------- | -| url | `valueof scalar string` | Url to the docs | -| description | `valueof scalar string` | Description of the docs | +| Name | Type | Description | +| ----------- | ---------------- | ----------------------- | +| url | `valueof string` | Url to the docs | +| description | `valueof string` | Description of the docs | ##### Examples @@ -138,9 +138,9 @@ Specify the OpenAPI `operationId` property for this operation. ##### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------- | -| operationId | `valueof scalar string` | Operation id value. | +| Name | Type | Description | +| ----------- | ---------------- | ------------------- | +| operationId | `valueof string` | Operation id value. | ##### Examples diff --git a/packages/openapi3/README.md b/packages/openapi3/README.md index 0648f87a67..a41e857f9b 100644 --- a/packages/openapi3/README.md +++ b/packages/openapi3/README.md @@ -103,7 +103,7 @@ Specify that `oneOf` should be used instead of `anyOf` for that union. ##### Target -`union Union | ModelProperty` +`Union | ModelProperty` ##### Parameters @@ -119,10 +119,10 @@ Specify an external reference that should be used inside of emitting this type. ##### Target -`union Model | ModelProperty` +`Model | ModelProperty` ##### Parameters -| Name | Type | Description | -| ---- | ----------------------- | -------------------------------------------------------------------- | -| ref | `valueof scalar string` | External reference(e.g. "../../common.json#/components/schemas/Foo") | +| Name | Type | Description | +| ---- | ---------------- | -------------------------------------------------------------------- | +| ref | `valueof string` | External reference(e.g. "../../common.json#/components/schemas/Foo") | diff --git a/packages/protobuf/README.md b/packages/protobuf/README.md index c3325f7b2b..5e364aadb7 100644 --- a/packages/protobuf/README.md +++ b/packages/protobuf/README.md @@ -71,9 +71,9 @@ The field index of a Protobuf message must: ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------ | -| index | `valueof scalar uint32` | The whole-number index of the field. | +| Name | Type | Description | +| ----- | ---------------- | ------------------------------------ | +| index | `valueof uint32` | The whole-number index of the field. | ##### Examples @@ -101,7 +101,7 @@ This decorator will force the emitter to check and emit a model. ##### Target -`` +`{}` ##### Parameters @@ -155,13 +155,13 @@ information. ##### Target -`` +`{}` ##### Parameters -| Name | Type | Description | -| ------------ | ------------------------------------------------------ | ---------------------------- | -| reservations | `valueof model string \| [uint32, uint32] \| uint32[]` | a list of field reservations | +| Name | Type | Description | +| ------------ | ------------------------------------------------ | ---------------------------- | +| reservations | `valueof string \| [uint32, uint32] \| uint32[]` | a list of field reservations | ##### Examples diff --git a/packages/rest/README.md b/packages/rest/README.md index 8735429f8a..6b7744b780 100644 --- a/packages/rest/README.md +++ b/packages/rest/README.md @@ -43,9 +43,9 @@ Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my ##### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ----------------------------------------------------------------------------- | -| name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. | +| Name | Type | Description | +| ---- | ---------------- | ----------------------------------------------------------------------------- | +| name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | #### `@actionSeparator` @@ -57,13 +57,13 @@ Defines the separator string that is inserted before the action name in auto-gen ##### Target -`union Model | ModelProperty | Operation` +`Model | ModelProperty | Operation` ##### Parameters -| Name | Type | Description | -| --------- | ---------------------------------- | ---------------------------------------------------------------- | -| seperator | `valueof union "/" \| ":" \| "/:"` | Seperator seperating the action segment from the rest of the url | +| Name | Type | Description | +| --------- | ---------------------------- | ---------------------------------------------------------------- | +| seperator | `valueof "/" \| ":" \| "/:"` | Seperator seperating the action segment from the rest of the url | #### `@autoRoute` @@ -75,7 +75,7 @@ This interface or operation should resolve its route automatically. To be used w ##### Target -`union Interface | Operation` +`Interface | Operation` ##### Parameters @@ -104,10 +104,10 @@ Specify this operation is a collection action. (Scopped to a resource, /pets/my- ##### Parameters -| Name | Type | Description | -| ------------ | ----------------------- | ----------------------------------------------------------------------------- | -| resourceType | `Model` | Resource marked with | -| name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. | +| Name | Type | Description | +| ------------ | ---------------- | ----------------------------------------------------------------------------- | +| resourceType | `Model` | Resource marked with | +| name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | #### `@copyResourceKeyParameters` @@ -123,9 +123,9 @@ Copy the resource key parameters on the model ##### Parameters -| Name | Type | Description | -| ------ | ----------------------- | ------------------------------------- | -| filter | `valueof scalar string` | Filter to exclude certain properties. | +| Name | Type | Description | +| ------ | ---------------- | ------------------------------------- | +| filter | `valueof string` | Filter to exclude certain properties. | #### `@createsOrReplacesResource` @@ -267,9 +267,9 @@ Mark this model as a resource type with a name. ##### Parameters -| Name | Type | Description | -| -------------- | ----------------------- | ---------------------- | -| collectionName | `valueof scalar string` | type's collection name | +| Name | Type | Description | +| -------------- | ---------------- | ---------------------- | +| collectionName | `valueof string` | type's collection name | #### `@segment` @@ -281,13 +281,13 @@ Defines the preceding path segment for a ##### Target -`union Model | ModelProperty | Operation` +`Model | ModelProperty | Operation` ##### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ---------------------------------------------------------------------------------------------- | -| name | `valueof scalar string` | Segment that will be inserted into the operation route before the path parameter's name field. | +| Name | Type | Description | +| ---- | ---------------- | ---------------------------------------------------------------------------------------------- | +| name | `valueof string` | Segment that will be inserted into the operation route before the path parameter's name field. | ##### Examples diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 4be0330567..83704e8874 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -1,4 +1,4 @@ -import { Type, ValueType, resolvePath } from "@typespec/compiler"; +import { Type, ValueType, getTypeName, resolvePath } from "@typespec/compiler"; import { readFile } from "fs/promises"; import { stringify } from "yaml"; import { @@ -30,7 +30,6 @@ import { section, table, } from "../utils/markdown.js"; -import { getTypeSignature } from "../utils/type-signature.js"; async function loadTemplate(projectRoot: string, name: string) { try { @@ -196,8 +195,11 @@ export class MarkdownRenderer { `${this.filename(namedType)}#${this.anchorId(namedType)}` ); } + return inlinecode( - "name" in type && typeof type.name === "string" ? type.name : getTypeSignature(type) + getTypeName(type, { + namespaceFilter: (ns) => !this.refDoc.namespaces.some((x) => x.name === ns.name), + }) ); } diff --git a/packages/tspd/test/emitters/markdown/model.test.ts b/packages/tspd/test/emitters/markdown/model.test.ts index 7cabecb726..19d24ccacb 100644 --- a/packages/tspd/test/emitters/markdown/model.test.ts +++ b/packages/tspd/test/emitters/markdown/model.test.ts @@ -153,6 +153,16 @@ describe("properties table", () => { }); }); + it.only("render enum properties", async () => { + await expectTable({ + code: ` + model Test { name: Bar.baz } + enum Bar { baz } + `, + rows: ["| name | `Bar.baz` | |"], + }); + }); + it("render properties with documentation", async () => { await expectTable({ code: `model Test { diff --git a/packages/versioning/README.md b/packages/versioning/README.md index 7494739cd0..abb940eab7 100644 --- a/packages/versioning/README.md +++ b/packages/versioning/README.md @@ -67,7 +67,7 @@ Identifies when the target was added. ##### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` ##### Parameters @@ -131,7 +131,7 @@ Identifies when the target was removed. ##### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` ##### Parameters @@ -166,14 +166,14 @@ Identifies when the target has been renamed. ##### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` ##### Parameters -| Name | Type | Description | -| ------- | ----------------------- | ------------------------------------------- | -| version | `EnumMember` | The version that the target was renamed in. | -| oldName | `valueof scalar string` | The previous name of the target. | +| Name | Type | Description | +| ------- | ---------------- | ------------------------------------------- | +| version | `EnumMember` | The version that the target was renamed in. | +| oldName | `valueof string` | The previous name of the target. | ##### Examples @@ -230,13 +230,13 @@ Identifies that a namespace or a given versioning enum member relies upon a vers ##### Target -`union EnumMember | Namespace` +`EnumMember | Namespace` ##### Parameters -| Name | Type | Description | -| -------------- | ------- | --------------------------------------------------------------------- | -| versionRecords | `Array` | The dependent library version(s) for the target namespace or version. | +| Name | Type | Description | +| -------------- | -------------- | --------------------------------------------------------------------- | +| versionRecords | `EnumMember[]` | The dependent library version(s) for the target namespace or version. | ##### Examples From 5186103259daa8ad670910da3d7f88562f69f514 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 26 Feb 2024 11:06:27 -0800 Subject: [PATCH 21/24] Fix --- docs/libraries/http/reference/decorators.md | 8 ++++---- packages/http/README.md | 8 ++++---- packages/tspd/src/ref-doc/emitters/markdown.ts | 4 ++++ packages/tspd/test/emitters/markdown/model.test.ts | 11 ++++++++++- 4 files changed, 22 insertions(+), 9 deletions(-) diff --git a/docs/libraries/http/reference/decorators.md b/docs/libraries/http/reference/decorators.md index d629ae7d2c..6de642ddac 100644 --- a/docs/libraries/http/reference/decorators.md +++ b/docs/libraries/http/reference/decorators.md @@ -301,10 +301,10 @@ it will be used as a prefix to the route URI of the operation. #### Parameters -| Name | Type | Description | -| ------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| path | `valueof string` | Relative route path. Cannot include query parameters. | -| options | `(anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| Name | Type | Description | +| ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `valueof string` | Relative route path. Cannot include query parameters. | +| options | `` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | #### Examples diff --git a/packages/http/README.md b/packages/http/README.md index 73f1fb9ffa..f00fd6c488 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -346,10 +346,10 @@ it will be used as a prefix to the route URI of the operation. ##### Parameters -| Name | Type | Description | -| ------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| path | `valueof string` | Relative route path. Cannot include query parameters. | -| options | `(anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| Name | Type | Description | +| ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `valueof string` | Relative route path. Cannot include query parameters. | +| options | `` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | ##### Examples diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 83704e8874..ef6c758ca6 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -196,6 +196,10 @@ export class MarkdownRenderer { ); } + // So we don't show (anonymous model) until this gets improved. + if (type.kind === "Model" && type.name === "" && type.properties.size > 0) { + return inlinecode(""); + } return inlinecode( getTypeName(type, { namespaceFilter: (ns) => !this.refDoc.namespaces.some((x) => x.name === ns.name), diff --git a/packages/tspd/test/emitters/markdown/model.test.ts b/packages/tspd/test/emitters/markdown/model.test.ts index 19d24ccacb..85bfd7285a 100644 --- a/packages/tspd/test/emitters/markdown/model.test.ts +++ b/packages/tspd/test/emitters/markdown/model.test.ts @@ -153,7 +153,7 @@ describe("properties table", () => { }); }); - it.only("render enum properties", async () => { + it("render enum properties", async () => { await expectTable({ code: ` model Test { name: Bar.baz } @@ -163,6 +163,15 @@ describe("properties table", () => { }); }); + it("render array properties", async () => { + await expectTable({ + code: ` + model Test { name: string[] } + `, + rows: ["| name | `string[]` | |"], + }); + }); + it("render properties with documentation", async () => { await expectTable({ code: `model Test { From fa43a175177eaa45624fb34ab3ed106c4e2d5bff Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 26 Feb 2024 11:17:49 -0800 Subject: [PATCH 22/24] Update .chronus/changes/ref-docs-models-2024-1-23-22-27-5.md --- .chronus/changes/ref-docs-models-2024-1-23-22-27-5.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md b/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md index 10cc5d1341..10ebce6ec4 100644 --- a/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md +++ b/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md @@ -3,6 +3,7 @@ changeKind: internal packages: - "@typespec/http" + - "@typespec/openapi3" - "@typespec/rest" - "@typespec/json-schema" - "@typespec/openapi" From 610d6e04f245a65c1a70ce947cd9813547276ed5 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Wed, 28 Feb 2024 20:57:26 -0800 Subject: [PATCH 23/24] merge --- docs/libraries/http/reference/decorators.md | 4 ++-- docs/libraries/openapi/reference/data-types.md | 13 ++++++++----- packages/http/README.md | 4 ++-- packages/tspd/src/ref-doc/emitters/markdown.ts | 2 +- 4 files changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/libraries/http/reference/decorators.md b/docs/libraries/http/reference/decorators.md index d21ea8e485..f9025ae3ba 100644 --- a/docs/libraries/http/reference/decorators.md +++ b/docs/libraries/http/reference/decorators.md @@ -304,7 +304,7 @@ it will be used as a prefix to the route URI of the operation. | Name | Type | Description | | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | path | `valueof string` | Relative route path. Cannot include query parameters. | -| options | `` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| options | `{...}` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | #### Examples @@ -410,7 +410,7 @@ Specify authentication for a whole service or specific methods. See the [documen #### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` #### Parameters diff --git a/docs/libraries/openapi/reference/data-types.md b/docs/libraries/openapi/reference/data-types.md index 98635d691c..04831f5d81 100644 --- a/docs/libraries/openapi/reference/data-types.md +++ b/docs/libraries/openapi/reference/data-types.md @@ -18,11 +18,14 @@ model TypeSpec.OpenAPI.AdditionalInfo #### Properties -| Name | Type | Description | -| --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- | -| termsOfService? | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL. | -| contact? | [`Contact`](./data-types.md#TypeSpec.OpenAPI.Contact) | The contact information for the exposed API. | -| license? | [`License`](./data-types.md#TypeSpec.OpenAPI.License) | The license information for the exposed API. | +| Name | Type | Description | +| --------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| title? | `string` | The title of the API. Overrides the `@service` title. | +| summary? | `string` | A short summary of the API. Overrides the `@summary` provided on the service namespace. | +| version? | `string` | The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version). | +| termsOfService? | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL. | +| contact? | [`Contact`](./data-types.md#TypeSpec.OpenAPI.Contact) | The contact information for the exposed API. | +| license? | [`License`](./data-types.md#TypeSpec.OpenAPI.License) | The license information for the exposed API. | ### `Contact` {#TypeSpec.OpenAPI.Contact} diff --git a/packages/http/README.md b/packages/http/README.md index a2c27e93e5..8af39b6941 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -349,7 +349,7 @@ it will be used as a prefix to the route URI of the operation. | Name | Type | Description | | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | path | `valueof string` | Relative route path. Cannot include query parameters. | -| options | `` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| options | `{...}` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | ##### Examples @@ -455,7 +455,7 @@ Specify authentication for a whole service or specific methods. See the [documen ##### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` ##### Parameters diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index ef6c758ca6..0ef1f0b7ef 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -198,7 +198,7 @@ export class MarkdownRenderer { // So we don't show (anonymous model) until this gets improved. if (type.kind === "Model" && type.name === "" && type.properties.size > 0) { - return inlinecode(""); + return inlinecode("{...}"); } return inlinecode( getTypeName(type, { From fa312fbcffad93bd46e417e0a19e5de520970d46 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Wed, 28 Feb 2024 21:16:42 -0800 Subject: [PATCH 24/24] fix tests --- packages/tspd/test/emitters/markdown/model.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/tspd/test/emitters/markdown/model.test.ts b/packages/tspd/test/emitters/markdown/model.test.ts index 85bfd7285a..07ea032c54 100644 --- a/packages/tspd/test/emitters/markdown/model.test.ts +++ b/packages/tspd/test/emitters/markdown/model.test.ts @@ -210,7 +210,7 @@ describe("properties table", () => { code: `model Test { name: string, nested: {val: string, age: int32, third?: boolean} }`, rows: [ "| name | `string` | |", - "| nested | `` | |", + "| nested | `{...}` | |", "| nested.val | `string` | |", "| nested.age | `int32` | |", "| nested.third? | `boolean` | |",