Skip to content

Update the client generation document to provide valid typespec samples #2237

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

Merged
merged 11 commits into from
May 27, 2025
Merged

Update the client generation document to provide valid typespec samples #2237

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
dcbd9c0
Update the client generation document to provide a validate typespec
lirenhe Feb 20, 2025
297c51b
Merge branch 'main' into doc-fix
lirenhe Feb 20, 2025
512afe5
Merge branch 'main' into doc-fix
lirenhe Feb 21, 2025
5ea4802
Merge branch 'main' into doc-fix
lirenhe Mar 5, 2025
5dcc4b5
Merge branch 'main' into doc-fix
lirenhe Mar 11, 2025
194d797
Merge branch 'main' into doc-fix
lirenhe May 27, 2025
bc407ad
Merge branch 'main' into doc-fix
lirenhe May 27, 2025
8f13f73
Update the JS content
lirenhe May 27, 2025
41d98bf
Merge branch 'doc-fix' of https://github.com/Azure/typespec-azure int…
lirenhe May 27, 2025
3e75d2b
be consistency to use typespec instead of tsp
lirenhe May 27, 2025
1192574
update the format
lirenhe May 27, 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
185 changes: 3 additions & 182 deletions website/src/content/docs/docs/howtos/Generate client libraries/06types.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -703,14 +703,6 @@ public final class Animal implements JsonSerializable<Animal> {
<ClientTabs>
<ClientTabItem lang="typespec" >

```typespec
model Animal {
name: string;
kind: string;
...Record<string | int32>;
}
```

```typespec
model Animal {
name: string;
Expand Down Expand Up @@ -963,7 +955,7 @@ TypeSpec uses `@discriminator` decorator to add a discriminator to a model.
<ClientTabs>
<ClientTabItem lang="typespec" >

TypeSpec now has two ways to represent a discriminated set.
Client emitters now only support a single way to represent a discriminated set in TypeSpec.

1. Use model

Expand Down Expand Up @@ -1005,20 +997,6 @@ model Ragdoll extends Cat {
}
```

2. Use union

```typespec
@discriminator("kind")
union Cat {
Siamese,
Ragdoll,
}

model Siamese {}

model Ragdoll {}
```

</ClientTabItem>
<ClientTabItem lang="tcgc">

Expand Down Expand Up @@ -1250,18 +1228,13 @@ about nullability by inspecting the type of a property.
model Foo {
basicNullableProperty: string | null;
modelNullableProperty: Bar | null;
unionNullableProperty: Bar | Baz | null;
enumNullableProperty: LR | null;
}

model Bar {
prop: string;
}

model Baz {
prop: int32;
}

enum LR {
left,
right,
Expand Down Expand Up @@ -1316,52 +1289,6 @@ A nullable type has kind `nullable` and property `valueType`. The kind of the ty
}
}
},
{
"kind": "property",
"name": "unionNullableProperty",
"serializedName": "unionNullableProperty",
"optional": false,
"type": {
"kind": "nullable",
"valueType": {
"kind": "union",
"values": [
{
"kind": "model",
"name": "Bar",
"properties": [
{
"kind": "property",
"name": "prop",
"serializedName": "prop",
"optional": false,
"type": {
"kind": "string",
"encode": "string"
}
}
]
},
{
"kind": "model",
"name": "Baz",
"properties": [
{
"kind": "property",
"name": "prop",
"serializedName": "prop",
"optional": false,
"type": {
"kind": "int32",
"encode": "int32"
}
}
]
}
]
}
}
},
{
"kind": "property",
"name": "enumNullableProperty",
Expand Down Expand Up @@ -1409,17 +1336,13 @@ from corehttp.utils import CaseInsensitiveEnumMeta
class Bar(_model_base.Model):
prop: Optional[str] = rest_field()

class Baz(_model_base.Model):
prop: Optional[str] = rest_field()

class LR(str, Enum, metaclass=CaseInsensitiveEnumMeta):
LEFT = "left"
RIGHT = "right"

class Foo(_model_base.Model):
basicNullableProperty: Optional[str] = rest_field()
modelNullableProperty: Optional["_models.Bar"] = rest_field()
unionNullableProperty: Optional[Union["_models.Bar", "_models.Baz"]] = rest_field()
enumNullableProperty: Optional["LR"] = rest_field()

```
Expand Down Expand Up @@ -2314,108 +2237,6 @@ public enum WidgetOrientation {
</ClientTabItem>
</ClientTabs>

### Union with multiple types

These are unions where the values don't share same type.

<ClientTabs>
<ClientTabItem lang="typespec" >

```typespec
model Shirt {
sizing: 32 | 34 | int32 | "small" | "medium" | string;
}
```

</ClientTabItem>
<ClientTabItem lang="tcgc">

```json
{
"kind": "union",
"name": "ShirtSizings",
"generatedName": true,
"values": [
{
"kind": "constant",
"value": 32,
"valueType": {
"kind": "int32"
}
},
{
"kind": "constant",
"value": 34,
"valueType": {
"kind": "int32"
}
},
{
"kind": "constant",
"value": "small",
"valueType": {
"kind": "string"
}
},
{
"kind": "constant",
"value": "medium",
"valueType": {
"kind": "string"
}
},
{
"kind": "string"
}
]
}
```

</ClientTabItem>
<ClientTabItem lang="python">

Python will generate this as a union since these entries don't share the same type

```python
from typing import Literal

type ShirtSizing = Literal[32] | Literal[34] | int | Literal["small"] | Literal["medium"] | str

model Shirt:
sizing: ShirtSizing
```

</ClientTabItem>
<ClientTabItem lang="csharp" >

```csharp
public partial class Shirt
{
public BinaryData Shirt;
}
```

</ClientTabItem>
<ClientTabItem lang="typescript" >

```typescript
export interface Shirt {
sizing: 32 | 34 | number | "small" | "medium" | string;
}
```

</ClientTabItem>
<ClientTabItem lang="java" >

```java
public final class Shirt {
private BinaryData sizing;
}
```

</ClientTabItem>
</ClientTabs>

## Enums

### Standard
Expand Down Expand Up @@ -2706,7 +2527,7 @@ We will take the `@encode` decorator into account, determining how we serialize
<ClientTabs>
<ClientTabItem lang="typespec" >

```tsp
```typespec
model Test {
@encode(DateTimeKnownEncoding.rfc3339)
prop: utcDateTime;
Expand Down Expand Up @@ -2769,7 +2590,7 @@ When you specify an encoding type, say that you want to encode an integer as a s
<ClientTabs>
<ClientTabItem lang="typespec" >

```tsp
```typespec
model Test {
@encode(string)
prop: int64;
Expand Down
13 changes: 12 additions & 1 deletion website/src/content/docs/docs/howtos/Generate client libraries/08methodInputs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,11 @@ This document outlines the method input signatures that language emitters will g
<ClientTabItem lang="typespec" >

```typespec
model User {
firstName: string;
lastName: string;
}

@get
op get(): User;
```
Expand Down Expand Up @@ -101,6 +106,11 @@ func (client *Client) Get(ctx context.Context, options *ClientGetOptions) (Clien
<ClientTabItem lang="typespec" >

```typespec
model User {
firstName: string;
lastName: string;
}

@post
op post(@body body: User): void;
```
Expand Down Expand Up @@ -624,7 +634,8 @@ model BlobProperties {
@path
name: string;

@header testHeader: string;
@header
testHeader: string;
}

@route("blob_properties/{name}")
Expand Down
Loading