Skip to content

Add ClientInitialization scenarios with optional parameters #3601

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Copilot wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add ClientInitialization scenarios with optional parameters #3601

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b09fd4d
Initial plan
Copilot Dec 1, 2025
1819d0d
Add ClientInitialization scenarios with optional parameters
Copilot Dec 1, 2025
d39b99c
Remove unnecessary models and inline optional parameters
Copilot Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .chronus/changes/optional-client-initialization-params-2025-12-1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
changeKind: feature
packages:
- "@azure-tools/azure-http-specs"
---

Add ClientInitialization scenarios with optional parameters and scenarios with both optional and required parameters
67 changes: 67 additions & 0 deletions packages/azure-http-specs/spec-summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -608,6 +608,73 @@ client.withQuery(id: "test-id"); // No need to pass name or region here
client.withBody({ name: "test-name" }); // No need to pass name or region here
```

### Azure_ClientGeneratorCore_ClientInitialization_OptionalAndRequiredParams

- Endpoints:
- `get /azure/client-generator-core/client-initialization/optional-and-required-params/with-query`
- `get /azure/client-generator-core/client-initialization/optional-and-required-params/with-body`

Client for testing a mix of optional and required parameters moved to client level.

Parameters elevated to client level:

- name: "test-name-value" (required header parameter)
- region: "us-west" (optional query parameter)

Some languages may add optional parameters as properties to ClientOptions while
required parameters are constructor arguments.

Expected client usage:

```ts
// With all parameters provided
const client = new OptionalAndRequiredParamsClient({
name: "test-name-value", // Required
region: "us-west" // Optional
});

client.withQuery(id: "test-id"); // No need to pass name or region here
client.withBody({ name: "test-name" }); // No need to pass name or region here

// With only required parameter
const clientRequiredOnly = new OptionalAndRequiredParamsClient({
name: "test-name-value" // Required
// region is omitted (optional)
});
```

### Azure_ClientGeneratorCore_ClientInitialization_OptionalParams

- Endpoints:
- `get /azure/client-generator-core/client-initialization/optional-params/with-query`
- `get /azure/client-generator-core/client-initialization/optional-params/with-body`

Client for testing optional parameters moved to client level.

Parameters elevated to client level (all optional):

- name: "test-name-value" (optional header parameter)
- region: "us-west" (optional query parameter)

Some languages may add optional parameters as properties to ClientOptions.

Expected client usage:

```ts
// With all optional parameters provided
const client = new OptionalParamsClient({
name: "test-name-value",
region: "us-west"
});

client.withQuery(id: "test-id"); // No need to pass name or region here
client.withBody({ name: "test-name" }); // No need to pass name or region here

// Without optional parameters (using defaults/omitting)
const clientNoParams = new OptionalParamsClient();
clientNoParams.withQuery(id: "test-id");
```

### Azure_ClientGeneratorCore_ClientInitialization_ParamAlias

- Endpoints:
Expand Down
95 changes: 95 additions & 0 deletions packages/azure-http-specs/specs/azure/client-generator-core/client-initialization/client.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,22 @@ model ParamAliasClientOptions {
blobName: string;
}

model OptionalParamsClientOptions {
@doc("Optional name parameter. This parameter is used as a header in all operations.")
name?: string;

@doc("Optional region parameter. This parameter is used as a query parameter.")
region?: string;
}

model OptionalAndRequiredParamsClientOptions {
@doc("Required name parameter. This parameter is used as a header in all operations.")
name: string;

@doc("Optional region parameter. This parameter is used as a query parameter.")
region?: string;
}

// Scenario 1: Header parameter moved to client level
@scenarioDoc("""
Client for testing header parameter moved to client level.
Expand Down Expand Up @@ -244,3 +260,82 @@ namespace ParentClient {
deleteStandalone is Service.ChildClient.deleteStandalone;
}
}

// Scenario 7: Optional parameters moved to client level
@scenarioDoc("""
Client for testing optional parameters moved to client level.

Parameters elevated to client level (all optional):
- name: "test-name-value" (optional header parameter)
- region: "us-west" (optional query parameter)

Some languages may add optional parameters as properties to ClientOptions.

Expected client usage:
```ts
// With all optional parameters provided
const client = new OptionalParamsClient({
name: "test-name-value",
region: "us-west"
});

client.withQuery(id: "test-id"); // No need to pass name or region here
client.withBody({ name: "test-name" }); // No need to pass name or region here

// Without optional parameters (using defaults/omitting)
const clientNoParams = new OptionalParamsClient();
clientNoParams.withQuery(id: "test-id");
```
""")
@scenario
@global.Azure.ClientGenerator.Core.client({
name: "OptionalParamsClient",
service: Service,
})
@global.Azure.ClientGenerator.Core.clientInitialization(OptionalParamsClientOptions)
@route("/optional-params")
interface OptionalParams {
withQuery is Service.OptionalParams.withQuery;
withBody is Service.OptionalParams.withBody;
}

// Scenario 8: Optional and required parameters moved to client level
@scenarioDoc("""
Client for testing a mix of optional and required parameters moved to client level.

Parameters elevated to client level:
- name: "test-name-value" (required header parameter)
- region: "us-west" (optional query parameter)

Some languages may add optional parameters as properties to ClientOptions while
required parameters are constructor arguments.

Expected client usage:
```ts
// With all parameters provided
const client = new OptionalAndRequiredParamsClient({
name: "test-name-value", // Required
region: "us-west" // Optional
});

client.withQuery(id: "test-id"); // No need to pass name or region here
client.withBody({ name: "test-name" }); // No need to pass name or region here

// With only required parameter
const clientRequiredOnly = new OptionalAndRequiredParamsClient({
name: "test-name-value" // Required
// region is omitted (optional)
});
```
""")
@scenario
@global.Azure.ClientGenerator.Core.client({
name: "OptionalAndRequiredParamsClient",
service: Service,
})
@global.Azure.ClientGenerator.Core.clientInitialization(OptionalAndRequiredParamsClientOptions)
@route("/optional-and-required-params")
interface OptionalAndRequiredParams {
withQuery is Service.OptionalAndRequiredParams.withQuery;
withBody is Service.OptionalAndRequiredParams.withBody;
}
26 changes: 26 additions & 0 deletions packages/azure-http-specs/specs/azure/client-generator-core/client-initialization/main.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,3 +131,29 @@ interface ChildClient {
@delete
deleteStandalone(@path blobName: string): void;
}

// Scenario 7: Optional parameters moved to client level
@doc("Operations with optional parameters that should be moved to client level")
@route("/optional-params")
interface OptionalParams {
@route("/with-query")
@get
withQuery(@header("name") name?: string, @query region?: string, @query id: string): void;

@route("/with-body")
@post
withBody(@header("name") name?: string, @query region?: string, @body body: Input): void;
}

// Scenario 8: Optional and required parameters mixed at client level
@doc("Operations with both optional and required parameters that should be moved to client level")
@route("/optional-and-required-params")
interface OptionalAndRequiredParams {
@route("/with-query")
@get
withQuery(...NameHeaderParam, @query region?: string, @query id: string): void;

@route("/with-body")
@post
withBody(...NameHeaderParam, @query region?: string, @body body: Input): void;
}
80 changes: 80 additions & 0 deletions packages/azure-http-specs/specs/azure/client-generator-core/client-initialization/mockapi.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,3 +221,83 @@ Scenarios.Azure_ClientGeneratorCore_ClientInitialization_ParentClient_ChildClien
kind: "MockApiDefinition",
},
]);

// Mock responses for OptionalParams scenario
Scenarios.Azure_ClientGeneratorCore_ClientInitialization_OptionalParams = passOnSuccess([
{
uri: "/azure/client-generator-core/client-initialization/optional-params/with-query",
method: "get",
request: {
query: {
id: "test-id",
region: "us-west",
},
headers: {
name: "test-name-value",
},
},
response: {
status: 204,
},
kind: "MockApiDefinition",
},
{
uri: "/azure/client-generator-core/client-initialization/optional-params/with-body",
method: "post",
request: {
query: {
region: "us-west",
},
headers: {
name: "test-name-value",
},
body: json({
name: "test-name",
}),
},
response: {
status: 204,
},
kind: "MockApiDefinition",
},
]);

// Mock responses for OptionalAndRequiredParams scenario
Scenarios.Azure_ClientGeneratorCore_ClientInitialization_OptionalAndRequiredParams = passOnSuccess([
{
uri: "/azure/client-generator-core/client-initialization/optional-and-required-params/with-query",
method: "get",
request: {
query: {
id: "test-id",
region: "us-west",
},
headers: {
name: "test-name-value",
},
},
response: {
status: 204,
},
kind: "MockApiDefinition",
},
{
uri: "/azure/client-generator-core/client-initialization/optional-and-required-params/with-body",
method: "post",
request: {
query: {
region: "us-west",
},
headers: {
name: "test-name-value",
},
body: json({
name: "test-name",
}),
},
response: {
status: 204,
},
kind: "MockApiDefinition",
},
]);