From 44f99c1b1535b9b471f661972eb1261cc3dcc466 Mon Sep 17 00:00:00 2001 From: "FAREAST\\renhel" Date: Thu, 31 Oct 2024 17:54:57 +0800 Subject: [PATCH 1/2] Update the document for client generation --- docs/howtos/Client Generation/01setup.mdx | 12 +++---- docs/howtos/Client Generation/02client.mdx | 37 +++++++++++++++++----- 2 files changed, 35 insertions(+), 14 deletions(-) diff --git a/docs/howtos/Client Generation/01setup.mdx b/docs/howtos/Client Generation/01setup.mdx index 9f12de1353..7bda24bd28 100644 --- a/docs/howtos/Client Generation/01setup.mdx +++ b/docs/howtos/Client Generation/01setup.mdx @@ -1,11 +1,11 @@ import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -# Setup for SDK customization +# Setup for SDK Customization -This page explains how to setup customization of a generator if necessary. +This page provides instructions on setting up customization for TypeSpec to include client-specific customizations in the generated code. -Your `package.json` needs to contains a link to the customization library, `typespec-client-generator-core`: +Ensure that your `package.json` includes a link to the customization library, `typespec-client-generator-core`: ```json { @@ -21,7 +21,7 @@ Your `package.json` needs to contains a link to the customization library, `type } ``` -Customization should always be done in a file called `client.tsp` along with the `main.tsp`. +Customization should be implemented in a file named `client.tsp`, which should be used alongside with the `main.tsp`. ```typespec // client.tsp @@ -30,10 +30,10 @@ import "@azure-tools/typespec-client-generator-core"; using Azure.ClientGenerator.Core; -// Your customizations here +// Add your customizations here ``` -Once you have a customization file, you should compile with your client.tsp to get output that includes the customizations: +After you've created your customization file, use the command `tsp compile client.tsp` to generate output that includes your customizations: ```shell tsp compile client.tsp diff --git a/docs/howtos/Client Generation/02client.mdx b/docs/howtos/Client Generation/02client.mdx index d6b66cdda4..0e4f0dc58e 100644 --- a/docs/howtos/Client Generation/02client.mdx +++ b/docs/howtos/Client Generation/02client.mdx @@ -3,17 +3,17 @@ import TabItem from "@theme/TabItem"; # Client hierarchy -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. +This page documents the default client hierarchy behavior as well as how to customize clients. To get a summary of the setup, please check out 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 Modular Emitter. +The JS RLC doesn't support client hierarchy customization and will ignore client.tsp. Therefore, the following scenarios won't affect the JS RLC user experience. In this context, the TypeScript part refers to the JS Modular Emitter. ## Default behavior -By default, each namespace with `@service` decorator will be generated as a root client. The name for that client will be the namespace name concatenating `Client` as suffix. +Each namespace with `@service` decorator will automatically be generated as a root client by default. The client's name will be the namespace name with `Client` added as suffix. -Other nested namespacess and interfaces of each root client will be generated as operation groups with hierarchy. +Nested namespaces and interfaces within each root client will be generated as operation groups with hierarchy. -Different language's code generator will have different way to organize clients and operation groups. Please refer the following examples. +Code generators for different languages will organize clients and operation groups in various ways. Please refer the following examples: ### Single client @@ -21,12 +21,19 @@ Different language's code generator will have different way to organize clients ```typespec +using TypeSpec.Versioning; +using TypeSpec.Http; + +@versioned(Versions) @service({ - title: "Pet Store", - version: "v1", + title: "Pet Store" }) namespace PetStore; +enum Versions { + v1, +} + @route("/feed") op feed(): void; @@ -50,9 +57,23 @@ client.pet() ```csharp +namespace PetStore +{ + public partial class PetStoreClient + { + public PetStoreClient(Uri endpoint, PetStoreClientOptions options){} + + public virtual async Task FeedAsync(RequestContext context = null) {} + public virtual Response Feed(RequestContext context = null) {} + public virtual async Task PetAsync(RequestContext context = null) {} + public virtual Response Pet(RequestContext context = null) {} + } +} + +// Create the client and invoke the operations using PetStore; -PetStoreClient client = new PetStoreClient(); +PetStoreClient client = new PetStoreClient(url, options); client.Feed(); client.Pet(); ``` From efa09d53055ddf62a5c1f19e8beea2dec9e30a5b Mon Sep 17 00:00:00 2001 From: "FAREAST\\renhel" Date: Fri, 1 Nov 2024 10:32:42 +0800 Subject: [PATCH 2/2] Fix pettier check error in the doc --- docs/howtos/Client Generation/02client.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howtos/Client Generation/02client.mdx b/docs/howtos/Client Generation/02client.mdx index 077f75c11c..49df194fcd 100644 --- a/docs/howtos/Client Generation/02client.mdx +++ b/docs/howtos/Client Generation/02client.mdx @@ -28,7 +28,7 @@ using TypeSpec.Http; @versioned(Versions) @service({ - title: "Pet Store" + title: "Pet Store", }) namespace PetStore;