From 9c5e8c4964ad05a8f4bc27626bda7f448d1fd7ec Mon Sep 17 00:00:00 2001 From: catalinaperalta Date: Thu, 29 Aug 2024 10:43:44 -0700 Subject: [PATCH] Update website docs to reflect renaming the client generation docs (#1444) Pushing changes to the website package to reflect the changes made to the client generation documentation in this PR: https://github.com/Azure/typespec-azure/pull/1294 Co-authored-by: Catalina Peralta --- .../00howtogen.mdx | 10 +- .../01setup.mdx | 4 +- .../02client.mdx | 6 +- .../03convenient.mdx | 10 +- .../04renaming.mdx | 8 +- .../05union.mdx | 6 +- .../06types.mdx | 13 +- .../07tcgcTypes.mdx | 377 +++++++++++++++++- .../08methodInputs.mdx | 0 .../09versioning.mdx | 0 .../10longRunningOperations.mdx | 201 ++++++++++ .../howtos/Client Generation/11etag.mdx | 71 ++++ 12 files changed, 671 insertions(+), 35 deletions(-) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/00howtogen.mdx (86%) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/01setup.mdx (86%) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/02client.mdx (98%) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/03convenient.mdx (97%) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/04renaming.mdx (97%) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/05union.mdx (96%) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/06types.mdx (98%) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/07tcgcTypes.mdx (81%) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/08methodInputs.mdx (100%) rename packages/website/versioned_docs/version-latest/howtos/{DataPlane Generation - DPG => Client Generation}/09versioning.mdx (100%) create mode 100644 packages/website/versioned_docs/version-latest/howtos/Client Generation/10longRunningOperations.mdx create mode 100644 packages/website/versioned_docs/version-latest/howtos/Client Generation/11etag.mdx diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/00howtogen.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/00howtogen.mdx similarity index 86% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/00howtogen.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/00howtogen.mdx index 9871d15309..59faa67f90 100644 --- a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/00howtogen.mdx +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/00howtogen.mdx @@ -1,9 +1,9 @@ import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -# How to generate DPG +# How to generate client libraries -This page documents how to build a Data-Plane SDK from your TYPESPEC specification. For an overview of the whole process from initial API design to shipping SDKs, please visit https://aka.ms/azsdk/dpcodegen. +This page documents how to build a client library from your TYPESPEC specification. For an overview of the whole process from initial API design to shipping SDKs, please visit https://aka.ms/azsdk/dpcodegen. The best documentation on how to generate can found using those links: @@ -15,11 +15,11 @@ The best documentation on how to generate can found using those links: At a glance, add your emitter name to your `package.json`, along with the right options in the `tspconfig.yaml`. -> **NOTE:** It may be complicated to generate all languages from the same folder at the moment as DPG and `typespec-azure-core` are still in preview. -> It's recommended that you keep each `package.json` with a unique language emitter, as they are likely to conflict, until all emitters and `typespec-azure-core` +> **NOTE:** It may be complicated to generate all languages from the same folder at the moment as the emitters and TypeSpec libraries, such as `typespec-azure-core` and `typespec-resource-manager` are still in preview. +> It's recommended that you keep each `package.json` with a unique language emitter, as they are likely to conflict, until all emitters and the TypeSpec libraries > reach their first stable release. -Update your `package.json` to contain dependencies on DPG language emitter(s). Don't forget to do `npm install` after an update of the file: +Update your `package.json` to contain dependencies on the language emitter(s). Don't forget to do `npm install` after an update of the file: ```json { diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/01setup.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/01setup.mdx similarity index 86% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/01setup.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/01setup.mdx index 7ecb427959..9f12de1353 100644 --- a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/01setup.mdx +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/01setup.mdx @@ -3,9 +3,9 @@ import TabItem from "@theme/TabItem"; # Setup for SDK customization -This page explains how to setup customization of DPG generator if necessary. +This page explains how to setup customization of a generator if necessary. -Your `package.json` needs to contains a link to the customization library for dpg, called `typespec-client-generator-core`: +Your `package.json` needs to contains a link to the customization library, `typespec-client-generator-core`: ```json { diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/02client.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/02client.mdx similarity index 98% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/02client.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/02client.mdx index 95098102f9..d6b66cdda4 100644 --- a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/02client.mdx +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/02client.mdx @@ -3,9 +3,9 @@ import TabItem from "@theme/TabItem"; # Client hierarchy -This page documents the default client hierarchy behavior as well as how to customize clients in DPG. For an overview of the setup, please visit the previous page. +This page documents the default client hierarchy behavior as well as how to customize clients. For an overview of the setup, please visit the previous page. -JS RLC is not in the business of customization. it will ignore client.tsp and the follow scenarios will not have impact on the JS RLC user experiences. In this context, TypeScript part means JS DPG. +JS RLC is not in the business of customization. it will ignore client.tsp and the follow scenarios will not have impact on the JS RLC user experiences. In this context, TypeScript part means JS Modular Emitter. ## Default behavior @@ -288,7 +288,7 @@ For this section, we will assume that you have service called `PetStore` in the ### Renaming the single client -This can be achieved with the augment operator and the DPG package +This can be achieved with the augment operator and the emitter package diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/03convenient.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/03convenient.mdx similarity index 97% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/03convenient.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/03convenient.mdx index 0b377a8de7..6f659ad8da 100644 --- a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/03convenient.mdx +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/03convenient.mdx @@ -3,7 +3,7 @@ import TabItem from "@theme/TabItem"; # Convenient method generation -This page documents how to customize method generations in DPG. For an overview of the setup, please visit the setup page. +This page documents how to customize method generation for the emitters. For an overview of the setup, please visit the setup page. ## Default behaviors @@ -38,7 +38,6 @@ op GetModel is ResourceRead; class OutputModel: name: str = rest_field(readonly=True) response: OutputModel = client.get(name="name") -FIXME ``` @@ -114,7 +113,7 @@ For fine tuning, the set of decorators `@protocolAPI` and `@convenientAPI` can b ### Shifting the generation of protocol and convenience on and off -This can be achieved with the augment operator and the DPG package +This can be achieved with the augment operator and the emitter package @@ -198,9 +197,8 @@ The two possible value for the `Access` enum are `internal` and `public`. ```python -class _GetModel: - ... -# FIXME +# can't import form models directly +from petstorenamespace.models import GetModel # will report error ``` diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/04renaming.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/04renaming.mdx similarity index 97% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/04renaming.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/04renaming.mdx index 3d0e32ad46..999fab1581 100644 --- a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/04renaming.mdx +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/04renaming.mdx @@ -3,7 +3,7 @@ import TabItem from "@theme/TabItem"; # Client renaming -This page documents how to customize names for client generations in DPG. For an overview of the setup, please visit the setup page. +This page documents how to customize names for client generation. For an overview of the setup, please visit the setup page. :::note The TypeSpec compiler provides an `@encodedName` decorator that allows changing the name of the property for a given serialization format. @@ -113,7 +113,7 @@ Renames in the context of models can be done on the model name and the attribute Language target takes priority over `client` target. -> **NOTE:** As model name do not get serialized as JSON, sometimes the best choice is to rename the main TYPESPEC for clarity. Talk to your DPG contact is you're unsure +> **NOTE:** As model name do not get serialized as JSON, sometimes the best choice is to rename the main TYPESPEC for clarity. Talk to your emitter contact is you're unsure > if you should rename the model in the main TYPESPEC or customize it. @@ -214,9 +214,7 @@ using Azure.ClientGenerator.Core; ```python class InputModel: input_name: str = rest_field(rest_name="name", readonly=True) - -client.get_computed_model(name="name") -# FIXME +response: InputModel = client.get_computed_model(name="name") ``` diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/05union.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/05union.mdx similarity index 96% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/05union.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/05union.mdx index 29dff03355..9e4a92bedd 100644 --- a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/05union.mdx +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/05union.mdx @@ -3,7 +3,7 @@ import TabItem from "@theme/TabItem"; # One path for multiple input/output -This page documents DPG behavior and customization when you use union operator `|` or `@sharedRoute` to express multiple input/output for a given path. +This page documents emitter behavior and customization when you use union operator `|` or `@sharedRoute` to express multiple input/output for a given path. ## Default behaviors @@ -37,11 +37,11 @@ op completions(@body input: CompletionInput): CompletionResult; ```python -def analyze(*, mode: Literal["strict", "lenient"], image: bytes) -> AnalyzeResult: +def analyze(image: bytes, *, mode: Literal["strict", "lenient"]) -> AnalyzeResult: ... class CompletionInput: - input: str | List[str] = rest_field(readonly=True) + input: Union[str, List[str]] = rest_field(readonly=True) def completions(input: CompletionInput) -> CompletionResult: ... diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/06types.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/06types.mdx similarity index 98% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/06types.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/06types.mdx index 0382d0caff..704d4a2420 100644 --- a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/06types.mdx +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/06types.mdx @@ -162,7 +162,7 @@ public partial class Foo : IUtf8JsonSerializable, IJsonModel -In Java, `@flattenProperty` have no effect on data-plane libraries. +In Java, `@flattenProperty` have no effect on generated libraries. ```java @Fluent @@ -247,7 +247,7 @@ model Animal is Record { -Python DPG model is original designed to support adding any additional properties. +Python models are designed to support adding any additional properties. ```python from .. import _model_base @@ -396,7 +396,7 @@ model Animal { -Python DPG model is original designed to support adding any additional properties. +Python models are designed to support adding any additional properties. ```python from typing import Any @@ -606,7 +606,7 @@ model Animal { -Python DPG model is original designed to support adding any additional properties. +Python models are designed to support adding any additional properties. ```python from .. import _model_base @@ -726,7 +726,7 @@ model Animal { -Python DPG model is original designed to support adding any additional properties. +Python models are designed to support adding any additional properties. ```python from .. import _model_base @@ -2372,7 +2372,8 @@ TODO; ```java -TODO +// Internal implementation +jsonWriter.writeStringField("prop", Objects.toString(this.value, null)); ``` diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/07tcgcTypes.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/07tcgcTypes.mdx similarity index 81% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/07tcgcTypes.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/07tcgcTypes.mdx index 68c25ca20a..162558a521 100644 --- a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/07tcgcTypes.mdx +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/07tcgcTypes.mdx @@ -150,7 +150,18 @@ const sdkContext = { kind: "http", ... } - } + }, + examples: [ + { + kind: "http", + name: "Example 1", + description: "Example 1", + filePath: "example1.json", + rawExample: {...}, + parameters: [...], + responses: {...} + } + ] }, response: { kind: "method", @@ -891,7 +902,10 @@ export interface SdkHttpOperation { kind: "http"; // raw HTTP operation output from typespec/http __raw: HttpOperation; + // route path for the target operation. TypeSpec suggest to use `uriTemplate` instead as `path` will not work for complex cases like not-escaping reserved chars. path: string; + // the fully resolved URI template for the target operation as defined by [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570). + uriTemplate: string; verb: HttpVerb; parameters: (SdkPathParameter | SdkQueryParameter | SdkHeaderParameter)[]; bodyParam: SdkBodyParameter; @@ -899,6 +913,7 @@ export interface SdkHttpOperation { // HttpStatusCodeRange can represent either a single status code or a range. responses: Map; exceptions: Map; + examples?: SdkHttpOperationExample[]; } ``` @@ -911,6 +926,7 @@ const sdkHttpOperation = { // raw HttpOperation from @typespec/http; }, path: "/widgets", + uriTemplate: "/widgets", verb: "get", parameters: [ { @@ -931,7 +947,18 @@ const sdkHttpOperation = { kind: "http", ... } - } + }, + examples: [ + { + kind: "http", + name: "Example 1", + description: "Example 1", + filePath: "example1.json", + rawExample: {...}, + parameters: [...], + responses: {...} + } + ] } ``` @@ -1040,13 +1067,24 @@ Currently we only support HTTP service parameters. This represents an HTTP query parameter. ```ts -export type CollectionFormat = "multi" | "csv" | "ssv" | "tsv" | "pipes"; +// different collection format to use to separate each value in array +// - multi: no separator, treat each value in array as a separate query parameter +// - csv: , as separator +// - ssv: space as separator +// - tsv: tab as separator +// - pipes: | as separator +// - simple: , as separator +// - form: no separator, treat each value in array as a separate query parameter +export type CollectionFormat = "multi" | "csv" | "ssv" | "tsv" | "pipes" | "simple" | "form"; export interface SdkQueryParameter extends SdkModelPropertyTypeBase { kind: "query"; + // the collection format to use to separate each value in array of a query parameter collectionFormat?: CollectionFormat; serializedName: string; correspondingMethodParams: SdkModelPropertyType[]; + // if true, send each value in array or object as a separate query parameter, default is `false` + explode: boolean; } ``` @@ -1055,7 +1093,15 @@ export interface SdkQueryParameter extends SdkModelPropertyTypeBase { This is an HTTP header parameter. ```ts -export type CollectionFormat = "multi" | "csv" | "ssv" | "tsv" | "pipes"; +// different collection format to use to separate each value in array +// - multi: no separator, treat each value in array as a separate header parameter +// - csv: , as separator +// - ssv: space as separator +// - tsv: tab as separator +// - pipes: | as separator +// - simple: , as separator +// - form: no separator, treat each value in array as a separate header parameter +export type CollectionFormat = "multi" | "csv" | "ssv" | "tsv" | "pipes" | "simple" | "form"; export interface SdkHeaderParameter extends SdkModelPropertyTypeBase { kind: "header"; @@ -1070,7 +1116,17 @@ export interface SdkHeaderParameter extends SdkModelPropertyTypeBase { ```ts export interface SdkPathParameter extends SdkModelPropertyTypeBase { kind: "path"; - urlEncode: boolean; + // when interpolating this parameter in the case of array or object, expand each value using the given style, default is `false` + explode: boolean; + // different interpolating styles for the path parameter, default is `"simple"` + // - simple: no separator + // - label: . as separator + // - matrix: ; as separator + // - fragment: # as separator + // - path: / as separator + style: "simple" | "label" | "matrix" | "fragment" | "path"; + // when interpolating this parameter, do not encode reserved characters, default is `false` + allowReserved: boolean; serializedName: string; optional: false; correspondingMethodParams: SdkModelPropertyType[]; @@ -1434,6 +1490,317 @@ export interface SdkEndpointType { } ``` +## Example Types + +The example types help to model the examples that TypeSpec author defined to help user understand how to use the API. + +We currently only have examples based on the payload, so the examples model will bind to the SdkServiceOperation. + +### Operation Related Interface + +These types are used to represent an example of a service operation. + +We currently only support HTTP calls to the service. + +So, we have `SdkHttpoperationExample` bind to `SdkHttpOperation`, `SdkHttpParameterExample` bind to `SdkHttpParameter`, `SdkHttpResponseExample` bind to `SdkHttpResponse`, and `SdkHttpResponseHeaderExample` bind to `SdkHttpResponseHeader`. + +Each type will have the example value type and its cooresponding definition type. + +```ts +interface SdkExampleBase { + kind: string; + name: string; + description: string; + filePath: string; + rawExample: any; +} + +export interface SdkHttpOperationExample extends SdkExampleBase { + kind: "http"; + parameters: SdkHttpParameterExample[]; + responses: Map; +} + +export interface SdkHttpParameterExample { + parameter: SdkHttpParameter; + value: SdkTypeExample; +} + +export interface SdkHttpResponseExample { + response: SdkHttpResponse; + headers: SdkHttpResponseHeaderExample[]; + bodyValue?: SdkTypeExample; +} + +export interface SdkHttpResponseHeaderExample { + header: SdkServiceResponseHeader; + value: SdkTypeExample; +} +``` + +### SdkExampleType + +These types are used to represent the example value of a type. One definition types will have different example value types. +For `SdkUnionExample`, since it is hard to determine whether the example value should belong to which union variant, we will keep the raw value and leave the work for the emitter. +For `SdkModelExample`, we will help to map the example type to the right subtype for the discriminated type, and we will separate the additional properties value from the property value. +But for the model with inheritance, we will not break down the type graph, just put all the example value in the child model. + +```ts +export type SdkTypeExample = + | SdkStringExample + | SdkNumberExample + | SdkBooleanExample + | SdkNullExample + | SdkAnyExample + | SdkArrayExample + | SdkDictionaryExample + | SdkUnionExample + | SdkModelExample; + +export interface SdkExampleTypeBase { + kind: string; + type: SdkType; + value: unknown; +} + +export interface SdkStringExample extends SdkExampleTypeBase { + kind: "string"; + type: + | SdkBuiltInType + | SdkDateTimeType + | SdkDurationType + | SdkEnumType + | SdkEnumValueType + | SdkConstantType; + value: string; +} + +export interface SdkNumberExample extends SdkExampleTypeBase { + kind: "number"; + type: + | SdkBuiltInType + | SdkDateTimeType + | SdkDurationType + | SdkEnumType + | SdkEnumValueType + | SdkConstantType; + value: number; +} + +export interface SdkBooleanExample extends SdkExampleTypeBase { + kind: "boolean"; + type: SdkBuiltInType | SdkConstantType; + value: boolean; +} + +export interface SdkNullExample extends SdkExampleTypeBase { + kind: "null"; + type: SdkNullableType; + value: null; +} + +export interface SdkAnyExample extends SdkExampleTypeBase { + kind: "any"; + type: SdkBuiltInType; + value: unknown; +} + +export interface SdkArrayExample extends SdkExampleTypeBase { + kind: "array"; + type: SdkArrayType; + value: SdkTypeExample[]; +} + +export interface SdkDictionaryExample extends SdkExampleTypeBase { + kind: "dict"; + type: SdkDictionaryType; + value: Record; +} + +export interface SdkUnionExample extends SdkExampleTypeBase { + kind: "union"; + type: SdkUnionType; + value: unknown; +} + +export interface SdkModelExample extends SdkExampleTypeBase { + kind: "model"; + type: SdkModelType; + value: Record; + additionalPropertiesValue?: Record; +} +``` + +### Example + +```ts +const sdkHttpOperationExample = { + kind: "http", + name: "Example 1", + description: "Example 1", + filePath: "example1.json", + rawExample: { + operationId: "Widgets_Read", + title: "Example 1", + parameters: { + id: "test", + }, + responses: { + 200: { + body: { + id: "test", + color: "red", + weight: 100, + }, + }, + }, + }, + parameters: [ + { + parameter: {}, // ref to the SdkHttpParameter + value: { + kind: "string", + type: {}, // ref to the SdkType + value: "test", + }, + }, + ], + responses: { + 200: { + response: {}, // ref to the SdkHttpResponse + bodyValue: { + kind: "model", + type: {}, // ref to the SdkType + value: { + id: { + kind: "string", + type: {}, // ref to the SdkType + value: "test", + }, + color: { + kind: "string", + type: {}, // ref to the SdkType + value: "red", + }, + weight: { + kind: "number", + type: {}, // ref to the SdkType + value: 100, + }, + }, + }, + }, + }, +}; +``` + +### Usage + +```ts +function serializeServiceOperationExample( + context: PythonSdkContext, + operation: SdkHttpOperation +): PythonSdkHttpOperationExample { + for (const example of operation.examples) { + return { + name: example.name, + filePath: example.filePath, + parameters: example.parameters.map((x) => ({ + parameter: getSdkModelPropertyType(x.parameter), + value: serializeTypeExample(context, x.value), + })), + responses: new Map( + [...example.responses].map(([key, value]) => [ + key, + { + response: serializeHttpResponse(value.response), + headers: value.headers.map((x) => ({ + header: getSdkModelPropertyType(x.header), + value: serializeTypeExample(context, x.value), + })), + bodyValue: serializeTypeExample(context, value.bodyValue), + }, + ]) + ), + }; + } +} + +function serializeTypeExample( + context: PythonSdkContext, + example: SdkTypeExample +): PythonSdkTypeExample { + switch (example.kind) { + case "string": + return { + ...example, + type: getPythonSdkType(context, example.type), + }; + case "number": + return { + ...example, + type: getPythonSdkType(context, example.type), + }; + case "boolean": + return { + ...example, + type: getPythonSdkType(context, example.type), + }; + case "null": + return { + ...example, + type: getPythonSdkType(context, example.type), + }; + case "any": + return { + ...example, + type: getPythonSdkType(context, example.type), + }; + case "array": + return { + ...example, + type: getPythonSdkType(context, example.type), + value: example.value.map((x) => serializeTypeExample(context, x)), + }; + case "dict": + return { + ...example, + type: getPythonSdkType(context, example.type), + value: Object.fromEntries( + Object.entries(example.value).map(([key, value]) => [ + key, + serializeTypeExample(context, value), + ]) + ), + }; + case "union": + return { + ...example, + type: getPythonSdkType(context, example.type), + }; + case "model": + return { + ...example, + type: getPythonSdkType(context, example.type), + value: Object.fromEntries( + Object.entries(example.value).map(([key, value]) => [ + key, + serializeTypeExample(context, value), + ]) + ), + additionalPropertiesValue: example.additionalPropertiesValue + ? Object.fromEntries( + Object.entries(example.additionalPropertiesValue).map(([key, value]) => [ + key, + serializeTypeExample(context, value), + ]) + ) + : undefined, + }; + } +} +``` + ## Complete Usage Code ### lib.ts diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/08methodInputs.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/08methodInputs.mdx similarity index 100% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/08methodInputs.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/08methodInputs.mdx diff --git a/packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/09versioning.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/09versioning.mdx similarity index 100% rename from packages/website/versioned_docs/version-latest/howtos/DataPlane Generation - DPG/09versioning.mdx rename to packages/website/versioned_docs/version-latest/howtos/Client Generation/09versioning.mdx diff --git a/packages/website/versioned_docs/version-latest/howtos/Client Generation/10longRunningOperations.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/10longRunningOperations.mdx new file mode 100644 index 0000000000..316206ca0a --- /dev/null +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/10longRunningOperations.mdx @@ -0,0 +1,201 @@ +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Long-Running Operations + +This doc details what emitters will generate for long-running operations. + +## Resource create or replace + +Long-running operation to create or replace a resource. + + + + +```typespec +alias ResourceOperations = global.Azure.Core.ResourceOperations; + +@resource("users") +@doc("Details about a user.") +model User { + @key + @visibility("read") + @doc("The name of user.") + name: string; + + @doc("The role of user") + role: string; +} + +// Operation for polling the status of the LRO. SDK may exclude this operation from client. +@sharedRoute +op getOperationStatus is ResourceOperations.GetResourceOperationStatus; + +@pollingOperation(getOperationStatus) +op createOrReplace is ResourceOperations.LongRunningResourceCreateOrReplace; +``` + + + + + +```python +def begin_create_or_replace( + self, name: str, resource: Union[User, JSON, IO[bytes]], **kwargs: Any +) -> LROPoller[User] +``` + + + + + +```csharp + +``` + + + + + +```typescript + +``` + + + + + +```java +public SyncPoller beginCreateOrReplace(String name, User resource); +``` + + + + +## Resource delete + +Long-running operation to delete a resource. + + + + +```typespec +@pollingOperation(getOperationStatus) +op delete is ResourceOperations.LongRunningResourceDelete; +``` + + + + + +```python +def begin_delete(self, name: str, **kwargs: Any) -> LROPoller[None] +``` + + + + + +```csharp + +``` + + + + + +```typescript + +``` + + + + + +```java +public SyncPoller beginDelete(String name); +``` + + + + +## Resource action + +Long-running operation to invoke an action on a resource. + + + + +```typespec +@resource("users") +@doc("Details about a user.") +model User { + @key + @visibility("read") + @doc("The name of user.") + name: string; + + @doc("The role of user") + role: string; +} + +@doc("The parameters for exporting a user.") +model UserExportParams { + @query + @doc("The format of the data.") + format: string; +} + +@doc("The exported user data.") +model ExportedUser { + @doc("The name of user.") + name: string; + + @doc("The exported URI.") + resourceUri: string; +} + +// Operation for polling the status of the LRO. SDK may exclude this operation from client. +@sharedRoute +op getExportOperationStatus is ResourceOperations.GetResourceOperationStatus; + +@pollingOperation(getExportOperationStatus) +op export is ResourceOperations.LongRunningResourceAction; +``` + + + + + +```python +def begin_export(self, name: str, *, format: str, **kwargs: Any) -> LROPoller[ExportedUser] +``` + + + + + +```csharp + +``` + + + + + +```typescript + +``` + + + + + +```java +public SyncPoller beginExport(String name, String format); +``` + + + diff --git a/packages/website/versioned_docs/version-latest/howtos/Client Generation/11etag.mdx b/packages/website/versioned_docs/version-latest/howtos/Client Generation/11etag.mdx new file mode 100644 index 0000000000..647c498bd4 --- /dev/null +++ b/packages/website/versioned_docs/version-latest/howtos/Client Generation/11etag.mdx @@ -0,0 +1,71 @@ +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Conditional Request Header + +This doc details what emitters will generate for conditional request header + +## `If-Match` and `If-None-Match` + + + + +```typespec +model Response { + name: string; +} + +@get +op get( + @header("If-Match") + @doc("The request should only proceed if an entity matches this string.") + ifMatch?: string, + + @header("If-None-Match") + @doc("The request should only proceed if no entity matches this string.") + ifNoneMatch?: string, +): Response; +``` + + + + + +```python +from azure.core import MatchConditions + +def get(self, *, etag: Optional[str] = None, match_condition: Optional[MatchConditions] = None) -> Response: +``` + + + + +```csharp + +``` + + + + +```typescript + +``` + + + + +```java +import com.azure.core.http.MatchConditions; + +public Response get(MatchConditions matchConditions); +``` + + + + +```go + +``` + + +