From f079f9a9f372332c4a03e9800bd0c30281559caf Mon Sep 17 00:00:00 2001 From: Yuchao Yan Date: Mon, 12 May 2025 15:38:24 +0800 Subject: [PATCH 1/7] init --- .../sdk_from_swagger_and_typespec.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/developer/sdk_from_swagger_and_typespec.md diff --git a/docs/developer/sdk_from_swagger_and_typespec.md b/docs/developer/sdk_from_swagger_and_typespec.md new file mode 100644 index 00000000000..25e29503077 --- /dev/null +++ b/docs/developer/sdk_from_swagger_and_typespec.md @@ -0,0 +1,149 @@ +# Overview + +This doc introdcues the difference between SDK generated from OpenAPI and typespec. + + +## Model + +### Model structure + +#### Msrest model + +The Azure Python Management SDK, generated from Swagger specifications using [@autorest/python](https://www.npmjs.com/package/@autorest/python), implements the msrest model pattern for SDK consumers. The following example illustrates the fundamental structure of an msrest model: + + +```python +from typing import Optional +from azure.mgmt.example._utils import serialization as _serialization + +class Person(_serialization.Model): + _attribute_map = { + "name": {"key": "name", "type": "str"}, + "parent_name": {"key": "parentName", "type": "str"}, + } + + def __init__(self, *, name: Optional[str] = None, parent_name: Optional[str] = None) -> None: + ... +``` + +### DPG model + +The Azure Python Management SDK, generated from [typespec](https://github.com/microsoft/typespec/) using [@azure-tools/typespec-python](https://www.npmjs.com/package/@azure-tools/typespec-python), implements the dpg model pattern. The following example demonstrates the fundamental structure of a dpg model: + +```python +from typing import Optional, Any, Mapping, overload +from azure.mgmt.example._utils.model_base import Model as _Model, rest_field + +class Person(_Model): + name: Optional[str] = rest_field() + parent_name: Optional[str] = rest_field(name="parentName") + + @overload + def __init__( + self, + *, + name: Optional[str] = None, + parent_name: Optional[str] = None, + ) -> None: ... + + @overload + def __init__(self, mapping: Mapping[str, Any]) -> None: ... + + + def __init__(self, *args: Any, **kwargs: Any) -> None: + super().__init__(*args, **kwargs) +``` + +### Model usage + +#### Msrest model usage + +```python +msrest_model = Person(name="xxx", parent_name="xxx") +print(msrest_model.name) +print(msrest_model.parent_name) + +# Access model as a dictionary +json_model = msrest_model.as_dict() +print(json_model["name"]) +print(json_model["parentName"]) +``` + +#### DPG model usage + +```python +dpg_model = Person(name="xxx", parent_name="xxx") +print(dpg_model.name) +print(dpg_model.parent_name) + +# Access model directly as a dictionary +print(dpg_model["name"]) +print(dpg_model["parentName"]) +``` + +### Model for flatten + +If property is marked with `"x-ms-flatten": "true"` (e.g. [here](https://azure.github.io/autorest/extensions/#x-ms-client-flatten)), nested property could be accessed directly in msrest model like: + +#### Simple flatten + +```python +class Person(_serialization.Model): + _attribute_map = { + "name": {"key": "properties.name", "type": "str"}, + } + + def __init__(self, *, name: Optional[str] = None) -> None: + ... + +msrest_model = Persion(name="xxx") +print(msrest_model.name) # A +print(msrest_model.properties.name) # equal to A +``` + +When the inner property name is same with outter property name, to avoid name duplicated, there will be prefix before the innter property name like: + +#### Bad flatten + +```python +class Person(_serialization.Model): + _attribute_map = { + "name": {"key": "name", "type": "str"}, + "properties_name": {"key": "properties.name", "type": "str"}, + } + + def __init__(self, *, name: Optional[str] = None) -> None: + ... + +msrest_model = Persion(name="xxx", properties_name="properties_name") +print(msrest_model.name) +print(msrest_model.properties_name) # A +print(msrest_model.properties.name) # equal to A +``` + +Since some swagger author abouse flatten, some property name has long and ugly prefix name which is not friendly for SDK user. Thus **DPG model don't support flatten**. + +#### NOTE + +For legacy SDKs which are genearted from swagger, after migration to typespec, we design a [compatible logic](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/07types/#flattening) to not break legacy SDK users. However, for deep nested flatten, legacy SDK users still have to update the code. + +```python +# msrest model +msrest_model = Model(...) + +print(msrest_model.properties_name) # A +print(msrest_model.properties.name) # equal to A +print(msrest_model.properties_properties_name) # B +print(msrest_model.properties.properties.name) # equal to B + +# after migrate to typespec +dpg_model = Model(...) +print(dpg_model.properties_name) # A, compatible with before but not recommend +print(msrest_model.properties.name) # equal to A +print(msrest_model.properties_properties_name) # B, can't work anymore +print(msrest_model.properties.properties.name) # legacy SDK users shall use model with this way +``` + +### additional_properties + + From 57a67551e40bc4d5d68abdac98ac83e548dd8fc6 Mon Sep 17 00:00:00 2001 From: Yuchao Yan Date: Tue, 13 May 2025 11:39:15 +0800 Subject: [PATCH 2/7] init --- .../sdk_from_swagger_and_typespec.md | 73 +++++++++++++++---- 1 file changed, 60 insertions(+), 13 deletions(-) diff --git a/docs/developer/sdk_from_swagger_and_typespec.md b/docs/developer/sdk_from_swagger_and_typespec.md index 25e29503077..89ec6a39940 100644 --- a/docs/developer/sdk_from_swagger_and_typespec.md +++ b/docs/developer/sdk_from_swagger_and_typespec.md @@ -1,7 +1,6 @@ # Overview -This doc introdcues the difference between SDK generated from OpenAPI and typespec. - +This doc introdcues the difference between Python SDK generated from swagger(OpenAPI) and typespec. In the following doc, we call the former swagger SDK and the latter typespec SDK. ## Model @@ -9,11 +8,9 @@ This doc introdcues the difference between SDK generated from OpenAPI and typesp #### Msrest model -The Azure Python Management SDK, generated from Swagger specifications using [@autorest/python](https://www.npmjs.com/package/@autorest/python), implements the msrest model pattern for SDK consumers. The following example illustrates the fundamental structure of an msrest model: - +Swagger SDK is generated from [Swagger specifications](https://github.com/Azure/azure-rest-api-specs/tree/main/specification) using [@autorest/python](https://www.npmjs.com/package/@autorest/python), and implements the Msrest model pattern for SDK consumers. The following example illustrates the fundamental structure of an Msrest model: ```python -from typing import Optional from azure.mgmt.example._utils import serialization as _serialization class Person(_serialization.Model): @@ -28,10 +25,9 @@ class Person(_serialization.Model): ### DPG model -The Azure Python Management SDK, generated from [typespec](https://github.com/microsoft/typespec/) using [@azure-tools/typespec-python](https://www.npmjs.com/package/@azure-tools/typespec-python), implements the dpg model pattern. The following example demonstrates the fundamental structure of a dpg model: +Typespec SDK is generated from [typespec](https://github.com/microsoft/typespec/) using [@azure-tools/typespec-python](https://www.npmjs.com/package/@azure-tools/typespec-python), and implements the DPG model pattern. The following example demonstrates the fundamental structure of a DPG model: ```python -from typing import Optional, Any, Mapping, overload from azure.mgmt.example._utils.model_base import Model as _Model, rest_field class Person(_Model): @@ -81,9 +77,15 @@ print(dpg_model["name"]) print(dpg_model["parentName"]) ``` +By comparing the usage, We can see that users could use DPG model as dictionary directly instead of calling `.as_dict()` as before, which is more convenient. + +#### NOTE for usage + +For backward compatibility, DPG model still supports `.as_dict()` for legacy SDK users. + ### Model for flatten -If property is marked with `"x-ms-flatten": "true"` (e.g. [here](https://azure.github.io/autorest/extensions/#x-ms-client-flatten)), nested property could be accessed directly in msrest model like: +If property is marked with `"x-ms-flatten": "true"` (e.g. [here](https://azure.github.io/autorest/extensions/#x-ms-client-flatten)), nested property could be accessed directly in Msrest model like: #### Simple flatten @@ -123,12 +125,12 @@ print(msrest_model.properties.name) # equal to A Since some swagger author abouse flatten, some property name has long and ugly prefix name which is not friendly for SDK user. Thus **DPG model don't support flatten**. -#### NOTE +#### NOTE for flatten For legacy SDKs which are genearted from swagger, after migration to typespec, we design a [compatible logic](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/07types/#flattening) to not break legacy SDK users. However, for deep nested flatten, legacy SDK users still have to update the code. ```python -# msrest model +# Msrest model msrest_model = Model(...) print(msrest_model.properties_name) # A @@ -140,10 +142,55 @@ print(msrest_model.properties.properties.name) # equal to B dpg_model = Model(...) print(dpg_model.properties_name) # A, compatible with before but not recommend print(msrest_model.properties.name) # equal to A -print(msrest_model.properties_properties_name) # B, can't work anymore -print(msrest_model.properties.properties.name) # legacy SDK users shall use model with this way +print(msrest_model.properties_properties_name) # can't work anymore +print(msrest_model.properties.properties.name) # legacy SDK users shall update code to use model with this way +``` + +### Additional properties + +#### Additional properties in Msrest model +To support [additional properties](https://www.apimatic.io/openapi/additionalproperties), Msrest model introduce a property named `additional_properties`: + +```python +msrest_model = Model(additional_properties={"hello": "world"}) +print(msrest_model) # output is `{"hello": "world"}` ``` -### additional_properties +#### Additional properties in DPG model +DPG model could accept any key just like a dictionary so it supports additional properties natively: +```python +dpg_model = Model({"hello": "world"}) +# or +dpg_model = Model() +dpg_model.update({"hello": "world"}) +# or +dpg_model = Model() +dpg_model["hello"] = "world" + +print(dpg_model) # output is `{"hello": "world"}` +``` +## Query/Header parameter in Operation + +Query/Header parameter in SDK generated from swagger is positional but in SDK generated from typespec is keyword only: + +```python + +client.operation("header", "query") # A +client.operation(header_parameter="header", query_parameter="query") # equal to A + +# After migration +client.operation("header", "query") # can't work anymore +client.operation(header_parameter="header", query_parameter="query") # OK +``` + + +## File name change +After migration, there are some changes for private file name but will not have any impact for SDK users. + +``` +_xxx_client.py => _client.py +_xxx_enums.py => _enum.py +_models_py3.py => _models.py +``` From 350e001ff00c304d526350c529edd27cdecd773f Mon Sep 17 00:00:00 2001 From: Yuchao Yan Date: Tue, 13 May 2025 11:50:00 +0800 Subject: [PATCH 3/7] agent update --- .../sdk_from_swagger_and_typespec.md | 91 +++++++++---------- 1 file changed, 45 insertions(+), 46 deletions(-) diff --git a/docs/developer/sdk_from_swagger_and_typespec.md b/docs/developer/sdk_from_swagger_and_typespec.md index 89ec6a39940..6fb910643e1 100644 --- a/docs/developer/sdk_from_swagger_and_typespec.md +++ b/docs/developer/sdk_from_swagger_and_typespec.md @@ -1,14 +1,14 @@ # Overview -This doc introdcues the difference between Python SDK generated from swagger(OpenAPI) and typespec. In the following doc, we call the former swagger SDK and the latter typespec SDK. +This document compares Python SDKs generated from Swagger (OpenAPI) specifications versus TypeSpec. For clarity, we'll refer to these as "Swagger SDKs" and "TypeSpec SDKs" respectively. ## Model -### Model structure +### Model Structure -#### Msrest model +#### Msrest Model -Swagger SDK is generated from [Swagger specifications](https://github.com/Azure/azure-rest-api-specs/tree/main/specification) using [@autorest/python](https://www.npmjs.com/package/@autorest/python), and implements the Msrest model pattern for SDK consumers. The following example illustrates the fundamental structure of an Msrest model: +Swagger SDKs are generated from [Swagger specifications](https://github.com/Azure/azure-rest-api-specs/tree/main/specification) using [@autorest/python](https://www.npmjs.com/package/@autorest/python), and implement the Msrest model pattern. The following example illustrates the fundamental structure of an Msrest model: ```python from azure.mgmt.example._utils import serialization as _serialization @@ -23,9 +23,9 @@ class Person(_serialization.Model): ... ``` -### DPG model +### DPG Model -Typespec SDK is generated from [typespec](https://github.com/microsoft/typespec/) using [@azure-tools/typespec-python](https://www.npmjs.com/package/@azure-tools/typespec-python), and implements the DPG model pattern. The following example demonstrates the fundamental structure of a DPG model: +TypeSpec SDKs are generated from [TypeSpec](https://github.com/microsoft/typespec/) using [@azure-tools/typespec-python](https://www.npmjs.com/package/@azure-tools/typespec-python), and implement the DPG model pattern. The following example demonstrates the fundamental structure of a DPG model: ```python from azure.mgmt.example._utils.model_base import Model as _Model, rest_field @@ -50,9 +50,9 @@ class Person(_Model): super().__init__(*args, **kwargs) ``` -### Model usage +### Model Usage -#### Msrest model usage +#### Msrest Model Usage ```python msrest_model = Person(name="xxx", parent_name="xxx") @@ -65,7 +65,7 @@ print(json_model["name"]) print(json_model["parentName"]) ``` -#### DPG model usage +#### DPG Model Usage ```python dpg_model = Person(name="xxx", parent_name="xxx") @@ -77,17 +77,17 @@ print(dpg_model["name"]) print(dpg_model["parentName"]) ``` -By comparing the usage, We can see that users could use DPG model as dictionary directly instead of calling `.as_dict()` as before, which is more convenient. +By comparing these usage patterns, we can see that DPG models can be accessed directly as dictionaries without calling `.as_dict()`, providing a more convenient experience. -#### NOTE for usage +#### Usage Note -For backward compatibility, DPG model still supports `.as_dict()` for legacy SDK users. +For backward compatibility, DPG models continue to support the `.as_dict()` method for existing SDK users. -### Model for flatten +### Model Flattening -If property is marked with `"x-ms-flatten": "true"` (e.g. [here](https://azure.github.io/autorest/extensions/#x-ms-client-flatten)), nested property could be accessed directly in Msrest model like: +When a property is marked with `"x-ms-flatten": "true"` (as described [here](https://azure.github.io/autorest/extensions/#x-ms-client-flatten)), nested properties can be accessed directly in Msrest models as follows: -#### Simple flatten +#### Simple Flattening Example ```python class Person(_serialization.Model): @@ -98,14 +98,14 @@ class Person(_serialization.Model): def __init__(self, *, name: Optional[str] = None) -> None: ... -msrest_model = Persion(name="xxx") +msrest_model = Person(name="xxx") print(msrest_model.name) # A -print(msrest_model.properties.name) # equal to A +print(msrest_model.properties.name) # equivalent to A ``` -When the inner property name is same with outter property name, to avoid name duplicated, there will be prefix before the innter property name like: +When an inner property name matches an outer property name, a prefix is added to avoid name collisions: -#### Bad flatten +#### Complex Flattening Example ```python class Person(_serialization.Model): @@ -117,47 +117,47 @@ class Person(_serialization.Model): def __init__(self, *, name: Optional[str] = None) -> None: ... -msrest_model = Persion(name="xxx", properties_name="properties_name") +msrest_model = Person(name="xxx", properties_name="properties_name") print(msrest_model.name) print(msrest_model.properties_name) # A -print(msrest_model.properties.name) # equal to A +print(msrest_model.properties.name) # equivalent to A ``` -Since some swagger author abouse flatten, some property name has long and ugly prefix name which is not friendly for SDK user. Thus **DPG model don't support flatten**. +Due to inconsistent usage of flattening in some Swagger specifications, property names can become unwieldy and user-unfriendly. For this reason, **DPG models do not support flattening**. -#### NOTE for flatten +#### Flattening Compatibility Note -For legacy SDKs which are genearted from swagger, after migration to typespec, we design a [compatible logic](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/07types/#flattening) to not break legacy SDK users. However, for deep nested flatten, legacy SDK users still have to update the code. +For legacy SDKs generated from Swagger that are migrated to TypeSpec, we've designed a [compatibility mechanism](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/07types/#flattening) to minimize breaking changes. However, for deeply nested flattened properties, code updates may be required: ```python # Msrest model msrest_model = Model(...) print(msrest_model.properties_name) # A -print(msrest_model.properties.name) # equal to A +print(msrest_model.properties.name) # equivalent to A print(msrest_model.properties_properties_name) # B -print(msrest_model.properties.properties.name) # equal to B +print(msrest_model.properties.properties.name) # equivalent to B -# after migrate to typespec +# After migration to TypeSpec dpg_model = Model(...) -print(dpg_model.properties_name) # A, compatible with before but not recommend -print(msrest_model.properties.name) # equal to A -print(msrest_model.properties_properties_name) # can't work anymore -print(msrest_model.properties.properties.name) # legacy SDK users shall update code to use model with this way +print(dpg_model.properties_name) # A, backwards compatible but not recommended +print(dpg_model.properties.name) # equivalent to A +print.dpg_model.properties_properties_name) # no longer works +print(dpg_model.properties.properties.name) # recommended approach after migration ``` -### Additional properties +### Additional Properties -#### Additional properties in Msrest model -To support [additional properties](https://www.apimatic.io/openapi/additionalproperties), Msrest model introduce a property named `additional_properties`: +#### Additional Properties in Msrest Models +To support [additional properties](https://www.apimatic.io/openapi/additionalproperties), Msrest models include an `additional_properties` parameter: ```python msrest_model = Model(additional_properties={"hello": "world"}) print(msrest_model) # output is `{"hello": "world"}` ``` -#### Additional properties in DPG model -DPG model could accept any key just like a dictionary so it supports additional properties natively: +#### Additional Properties in DPG Models +DPG models inherently support additional properties through dictionary-like behavior: ```python dpg_model = Model({"hello": "world"}) @@ -171,23 +171,22 @@ dpg_model["hello"] = "world" print(dpg_model) # output is `{"hello": "world"}` ``` -## Query/Header parameter in Operation +## Query/Header Parameters in Operations -Query/Header parameter in SDK generated from swagger is positional but in SDK generated from typespec is keyword only: +Query and header parameters in Swagger-generated SDKs are positional, while in TypeSpec-generated SDKs they are keyword-only: ```python - +# Swagger SDK client.operation("header", "query") # A -client.operation(header_parameter="header", query_parameter="query") # equal to A +client.operation(header_parameter="header", query_parameter="query") # equivalent to A -# After migration -client.operation("header", "query") # can't work anymore -client.operation(header_parameter="header", query_parameter="query") # OK +# After migration to TypeSpec +client.operation("header", "query") # no longer works +client.operation(header_parameter="header", query_parameter="query") # correct approach ``` - -## File name change -After migration, there are some changes for private file name but will not have any impact for SDK users. +## File Name Changes +After migration, some internal file names change, but these changes do not affect SDK users: ``` _xxx_client.py => _client.py From 274dcfddd3e4290f7f65d8f175a9dbc70b3d7ab3 Mon Sep 17 00:00:00 2001 From: Yuchao Yan Date: Tue, 13 May 2025 13:59:32 +0800 Subject: [PATCH 4/7] Update sdk_from_swagger_and_typespec.md --- docs/developer/sdk_from_swagger_and_typespec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer/sdk_from_swagger_and_typespec.md b/docs/developer/sdk_from_swagger_and_typespec.md index 6fb910643e1..530e201e573 100644 --- a/docs/developer/sdk_from_swagger_and_typespec.md +++ b/docs/developer/sdk_from_swagger_and_typespec.md @@ -153,7 +153,7 @@ To support [additional properties](https://www.apimatic.io/openapi/additionalpro ```python msrest_model = Model(additional_properties={"hello": "world"}) -print(msrest_model) # output is `{"hello": "world"}` +print(msrest_model.as_dict()) # output is `{"hello": "world"}` ``` #### Additional Properties in DPG Models From 0996a03df7e9ae875f116fb838392cd6b5f96072 Mon Sep 17 00:00:00 2001 From: msyyc <70930885+msyyc@users.noreply.github.com> Date: Wed, 14 May 2025 10:32:14 +0800 Subject: [PATCH 5/7] update for review --- docs/developer/sdk_from_swagger_and_typespec.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/developer/sdk_from_swagger_and_typespec.md b/docs/developer/sdk_from_swagger_and_typespec.md index 530e201e573..b8007e9d09d 100644 --- a/docs/developer/sdk_from_swagger_and_typespec.md +++ b/docs/developer/sdk_from_swagger_and_typespec.md @@ -2,7 +2,7 @@ This document compares Python SDKs generated from Swagger (OpenAPI) specifications versus TypeSpec. For clarity, we'll refer to these as "Swagger SDKs" and "TypeSpec SDKs" respectively. -## Model +## Model ### Model Structure @@ -11,8 +11,6 @@ This document compares Python SDKs generated from Swagger (OpenAPI) specificatio Swagger SDKs are generated from [Swagger specifications](https://github.com/Azure/azure-rest-api-specs/tree/main/specification) using [@autorest/python](https://www.npmjs.com/package/@autorest/python), and implement the Msrest model pattern. The following example illustrates the fundamental structure of an Msrest model: ```python -from azure.mgmt.example._utils import serialization as _serialization - class Person(_serialization.Model): _attribute_map = { "name": {"key": "name", "type": "str"}, @@ -28,8 +26,6 @@ class Person(_serialization.Model): TypeSpec SDKs are generated from [TypeSpec](https://github.com/microsoft/typespec/) using [@azure-tools/typespec-python](https://www.npmjs.com/package/@azure-tools/typespec-python), and implement the DPG model pattern. The following example demonstrates the fundamental structure of a DPG model: ```python -from azure.mgmt.example._utils.model_base import Model as _Model, rest_field - class Person(_Model): name: Optional[str] = rest_field() parent_name: Optional[str] = rest_field(name="parentName") @@ -149,6 +145,7 @@ print(dpg_model.properties.properties.name) # recommended approach after migrati ### Additional Properties #### Additional Properties in Msrest Models + To support [additional properties](https://www.apimatic.io/openapi/additionalproperties), Msrest models include an `additional_properties` parameter: ```python @@ -157,6 +154,7 @@ print(msrest_model.as_dict()) # output is `{"hello": "world"}` ``` #### Additional Properties in DPG Models + DPG models inherently support additional properties through dictionary-like behavior: ```python @@ -171,7 +169,9 @@ dpg_model["hello"] = "world" print(dpg_model) # output is `{"hello": "world"}` ``` -## Query/Header Parameters in Operations +## Operations + +### Query/Header Parameters in Operations Query and header parameters in Swagger-generated SDKs are positional, while in TypeSpec-generated SDKs they are keyword-only: @@ -186,6 +186,7 @@ client.operation(header_parameter="header", query_parameter="query") # correct a ``` ## File Name Changes + After migration, some internal file names change, but these changes do not affect SDK users: ``` @@ -193,3 +194,7 @@ _xxx_client.py => _client.py _xxx_enums.py => _enum.py _models_py3.py => _models.py ``` + +### File Name Note + +Files that name starts with `_` are internal files. From 7f6fd48d9c7e87fe6d647f299d3bffd3abc92355 Mon Sep 17 00:00:00 2001 From: msyyc <70930885+msyyc@users.noreply.github.com> Date: Wed, 14 May 2025 10:35:18 +0800 Subject: [PATCH 6/7] review --- docs/developer/sdk_from_swagger_and_typespec.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/developer/sdk_from_swagger_and_typespec.md b/docs/developer/sdk_from_swagger_and_typespec.md index b8007e9d09d..280449527f7 100644 --- a/docs/developer/sdk_from_swagger_and_typespec.md +++ b/docs/developer/sdk_from_swagger_and_typespec.md @@ -21,7 +21,7 @@ class Person(_serialization.Model): ... ``` -### DPG Model +#### DPG Model TypeSpec SDKs are generated from [TypeSpec](https://github.com/microsoft/typespec/) using [@azure-tools/typespec-python](https://www.npmjs.com/package/@azure-tools/typespec-python), and implement the DPG model pattern. The following example demonstrates the fundamental structure of a DPG model: @@ -169,6 +169,10 @@ dpg_model["hello"] = "world" print(dpg_model) # output is `{"hello": "world"}` ``` +#### Additional Properties Note + +DPG models don't have property named `additional_properties` anymore. + ## Operations ### Query/Header Parameters in Operations From c0b4c3ca5b35fb1b88853849b607bf428956d38f Mon Sep 17 00:00:00 2001 From: msyyc <70930885+msyyc@users.noreply.github.com> Date: Wed, 14 May 2025 11:50:05 +0800 Subject: [PATCH 7/7] review --- docs/developer/sdk_from_swagger_and_typespec.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/developer/sdk_from_swagger_and_typespec.md b/docs/developer/sdk_from_swagger_and_typespec.md index 280449527f7..79eecce1f56 100644 --- a/docs/developer/sdk_from_swagger_and_typespec.md +++ b/docs/developer/sdk_from_swagger_and_typespec.md @@ -95,9 +95,8 @@ class Person(_serialization.Model): ... msrest_model = Person(name="xxx") -print(msrest_model.name) # A -print(msrest_model.properties.name) # equivalent to A -``` +print(msrest_model.name) # equivalent to `msrest_model.serialize()["properties"]["name"]` +``` When an inner property name matches an outer property name, a prefix is added to avoid name collisions: @@ -115,8 +114,7 @@ class Person(_serialization.Model): msrest_model = Person(name="xxx", properties_name="properties_name") print(msrest_model.name) -print(msrest_model.properties_name) # A -print(msrest_model.properties.name) # equivalent to A +print(msrest_model.properties_name) # equivalent to `msrest_model.serialize()["properties"]["name"]` ``` Due to inconsistent usage of flattening in some Swagger specifications, property names can become unwieldy and user-unfriendly. For this reason, **DPG models do not support flattening**. @@ -129,10 +127,8 @@ For legacy SDKs generated from Swagger that are migrated to TypeSpec, we've desi # Msrest model msrest_model = Model(...) -print(msrest_model.properties_name) # A -print(msrest_model.properties.name) # equivalent to A -print(msrest_model.properties_properties_name) # B -print(msrest_model.properties.properties.name) # equivalent to B +print(msrest_model.properties_name) # A, equivalent to `msrest_model.serialize()["properties"]["name"]` +print(msrest_model.properties_properties_name) # B, equivalent to `msrest_model.serialize()["properties"]["properties"]["name"]` # After migration to TypeSpec dpg_model = Model(...)