Skip to content
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

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

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

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 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
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>;
}
```

Comment on lines -706 to -713
Copy link
Member

@tadelesh tadelesh Mar 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if we do not support union type, we could also remove this section.

```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">

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the next line could be removed.

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