TypeSpec Data Plane Generation library

npm install @azure-tools/typespec-client-generator-core

• @access
• @client
• @clientFormat
• @clientName
• @convenientAPI
• @exclude
• @flattenProperty
• @include
• @internal
• @operationGroup
• @protocolAPI
• @usage

Set explicit access for operations, models and enums. When setting access for models, the access info wll not be propagated to models' properties, base models or sub models. When setting access for an operation, it will influence the access info for models/enums that are used by this operation. Models/enums that are used in any operations with @access(Access.public) will be implicitly set to access "public" Models/enums that are only used in operations with @access(Access.internal) will be implicitly set to access "internal". This influence will be propagated to models' properties, parent models, discriminated sub models. But this influence will be override by @usage decorator on models/enums directly. If an operation/model/enum has no @access decorator and is not influenced by any operation with @access decorator, the access result is undefined.

@Azure.ClientGenerator.Core.access(value: EnumMember, scope?: valueof string)

Model | Operation | Enum | Union

// Access.internal
@access(Access.internal)
model ModelToHide {
prop: string;
}
// Access.internal
@access(Access.internal)
op test: void;

// Access.internal
@discriminator("kind")
model Fish {
  age: int32;
}

// Access.internal
@discriminator("sharktype")
model Shark extends Fish {
  kind: "shark";
  origin: Origin;
}

// Access.internal
model Salmon extends Fish {
  kind: "salmon";
}

// Access.internal
model SawShark extends Shark {
  sharktype: "saw";
}

// Access.internal
model Origin {
  country: string;
  city: string;
  manufacture: string;
}

// Access.internal
@get
@access(Access.internal)
op getModel(): Fish;

// Access.internal
model Test1 {}

// Access.internal
@access(Access.internal)
@route("/func1")
op func1(@body body: Test1): void;

// undefined
model Test2 {}

// undefined
@route("/func2")
op func2(@body body: Test2): void;

// Access.public
model Test3 {}

// Access.public
@access(Access.public)
@route("/func3")
op func3(@body body: Test3): void;

// undefined
model Test4 {}

// Access.internal
@access(Access.internal)
@route("/func4")
op func4(@body body: Test4): void;

// undefined
@route("/func5")
op func5(@body body: Test4): void;

// Access.public
model Test5 {}

// Access.internal
@access(Access.internal)
@route("/func6")
op func6(@body body: Test5): void;

// undefined
@route("/func7")
op func7(@body body: Test5): void;

// Access.public
@access(Access.public)
@route("/func8")
op func8(@body body: Test5): void;

Create a ClientGenerator.Core client out of a namespace or interface

@Azure.ClientGenerator.Core.client(value?: {}, scope?: valueof string)

Namespace | Interface

@client
namespace MyService {

}

namespace MyService {

}

@client({
  service: MyService,
})
interface MyInterface {}

@client({
  client: MySpecialClient,
})
interface MyInterface {}

DEPRECATED: Use @encode decorator in @typespec/compiler instead.

Can be used to explain the client type that the current TYPESPEC type should map to.

@Azure.ClientGenerator.Core.clientFormat(value: valueof "unixtime" | "iso8601" | "rfc1123" | "seconds")

ModelProperty

model MyModel {
  @clientFormat("unixtime")
  created_at?: int64;
}

Changes the name of a method, parameter, property, or model generated in the client SDK

@Azure.ClientGenerator.Core.clientName(rename: valueof string, scope?: valueof string)

unknown

@clientName("nameInClient")
op nameInService: void;

@clientName("nameForJava", "java")
@clientName("name_for_python", "python")
@clientName("nameForCsharp", "csharp")
@clientName("nameForJavascript", "javascript")
op nameInService: void;

Whether you want to generate an operation as a convenient operation.

@Azure.ClientGenerator.Core.convenientAPI(value?: valueof boolean, scope?: valueof string)

Operation

@convenientAPI(false)
op test: void;

DEPRECATED: Use @usage and @access decorator instead.

Whether to exclude a model from generation for specific languages. By default we generate all models that are included in operations.

@Azure.ClientGenerator.Core.exclude(scope?: valueof string)

Model

@exclude("python")
model ModelToExclude {
  prop: string;
}

Set whether a model property should be flattened or not.

@Azure.ClientGenerator.Core.flattenProperty(scope?: valueof string)

ModelProperty

model Foo {
  @flattenProperty
  prop: Bar;
}
model Bar {}

DEPRECATED: Use @usage and @access decorator instead.

Whether to include a model in generation for specific languages. By default we generate all models that are included in operations.

@Azure.ClientGenerator.Core.include(scope?: valueof string)

Model

@include("python")
model ModelToInclude {
  prop: string;
}

DEPRECATED: Use @access decorator instead.

Whether to mark an operation as internal for specific languages, meaning it should not be exposed to end SDK users

@Azure.ClientGenerator.Core.internal(scope?: valueof string)

Operation

@internal("python")
op test: void;

Create a ClientGenerator.Core operation group out of a namespace or interface

@Azure.ClientGenerator.Core.operationGroup(scope?: valueof string)

Namespace | Interface

@operationGroup
interface MyInterface {}

Whether you want to generate an operation as a protocol operation.

@Azure.ClientGenerator.Core.protocolAPI(value?: valueof boolean, scope?: valueof string)

Operation

@protocolAPI(false)
op test: void;

Expand usage for models/enums. A model/enum's default usage info is always calculated by the operations that use it. You could use this decorator to expand the default usage info. For example, with operation definition op test(): OutputModel, the model OutputModel has default usage Usage.output. After adding decorator @@usage(OutputModel, Usage.input), the final usage result for OutputModel is Usage.input | Usage.output. The calculation of default usage info for models will be propagated to models' properties, parent models, discriminated sub models. But the expanded usage from @usage decorator will not be propagated. If you want to do any customization for the usage of a model, you need to take care of all related models/enums.

@Azure.ClientGenerator.Core.usage(value: EnumMember | Union, scope?: valueof string)

Model | Enum | Union

op test(): OutputModel;

// usage result for `OutputModel` is `Usage.input | Usage.output`
@usage(Usage.input)
model OutputModel {
  prop: string;
}

// Usage.output
@discriminator("kind")
model Fish {
  age: int32;
}

// Usage.input | Usage.output
@discriminator("sharktype")
@usage(Usage.input)
model Shark extends Fish {
  kind: "shark";
  origin: Origin;
}

// Usage.output
model Salmon extends Fish {
  kind: "salmon";
}

// Usage.output
model SawShark extends Shark {
  sharktype: "saw";
}

// Usage.output
model Origin {
  country: string;
  city: string;
  manufacture: string;
}

@get
op getModel(): Fish;