swagger-codegen 生成 C SDK 中的 ArrayTest 模型：OpenAPI 嵌套数组属性的映射与实现解析

开发工具代码生成API设计【免费下载链接】swagger-codegenswagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.项目地址https://gitcode.com/gh_mirrors/sw/swagger-codegen点击查看免费下载ArrayTest 是 swagger-codegen 在 Petstore 测试样例中用于验证数组尤其是嵌套数组属性映射能力的 OpenAPI 模型。本文以samples/client/petstore/csharp/SwaggerClientNet40/docs/ArrayTest.md为骨架结合仓库内的 OpenAPI 定义、生成的 C# 源码与生成器单元测试完整讲解该模型从规格定义到 .NET 4.0 客户端类的映射过程读完可掌握数组属性、嵌套数组、模型引用在 C# SDK 中的真实落地形态以及如何在自己的 OpenAPI 定义中正确编写这类结构。模型文档说了什么ArrayTest是自动生成的 C# SDK面向 .NET 4.0 / Windows Phone 7.1中的一个数据模型类位于命名空间IO.Swagger.Model。其文档页以标准属性表格形式列出三个可选属性NameTypeDescriptionNotesArrayOfStringListstring[optional]ArrayArrayOfIntegerListListlong?[optional]ArrayArrayOfModelListListReadOnlyFirst[optional]三个属性均为可选[optional]且覆盖了三种数组形态一维字符串数组、二维整数数组int64、二维模型对象数组。这组属性并非凭空设计而是对应仓库中用于测试的 OpenAPI 规格定义。规格源头OpenAPI 中的数组定义ArrayTest 模型的规格定义位于 fixtures/immutable/specifications/v2/petstorefake.yaml同一测试规格另有副本存放于modules/swagger-codegen/src/test/resources/2_0/petstore-with-fake-endpoints-models-for-testing.yamlArrayTest: type: object properties: array_of_string: type: array items: type: string array_array_of_integer: type: array items: type: array items: type: integer format: int64 array_array_of_model: type: array items: type: array items: $ref: #/definitions/ReadOnlyFirst注意三点属性名采用 snake_casearray_of_string等生成器在 C# 中自动转换为 PascalCaseArrayOfString并通过[DataMember(Name...)]保留原始 JSON 键名保证网络传输与规格一致嵌套数组通过「数组的元素仍是数组」表达即type: array的items再次声明type: array映射到 C# 即为ListListT数组元素可以是$ref引用的模型ReadOnlyFirst即本 SDK 中的另一个模型类其本身只有Bar、Baz两个字符串属性见 ReadOnlyFirst.md。规格中还保留了被注释掉的array_of_enum用例注释说明「并非所有语言都能处理数组内枚举」因此该字段未进入生成结果——这也是理解 ArrayTest 为什么只包含三个属性的关键背景。生成的 C# 类从属性到完整 POCO生成的模型类位于 samples/client/petstore/csharp/SwaggerClientNet40/src/IO.Swagger/Model/ArrayTest.cs是一个标准的 C# POCOPlain Old CLR Object实现IEquatableArrayTest与IValidatableObject接口。属性声明与 JSON 契约[DataContract] public partial class ArrayTest : IEquatableArrayTest, IValidatableObject { [DataMember(Namearray_of_string, EmitDefaultValuefalse)] public Liststring ArrayOfString { get; set; } [DataMember(Namearray_array_of_integer, EmitDefaultValuefalse)] public ListListlong? ArrayArrayOfInteger { get; set; } [DataMember(Namearray_array_of_model, EmitDefaultValuefalse)] public ListListReadOnlyFirst ArrayArrayOfModel { get; set; } }关键映射细节stringOpenAPItype: string→ C#Liststringinteger format: int64→ C#long?可空long因此嵌套后为ListListlong?可空类型保证 JSON 中缺省字段不会反序列化为 0$ref: #/definitions/ReadOnlyFirst→ C# 类型ReadOnlyFirst嵌套后为ListListReadOnlyFirst所有属性使用EmitDefaultValuefalse即值为null或默认值时序列化会跳过该字段避免输出冗余的array_of_string: null。构造函数与默认值生成的构造函数为每个属性提供可选参数便于对象初始化Object Initializer 亦可二者可混用public ArrayTest( Liststring arrayOfString default(Liststring), ListListlong? arrayArrayOfInteger default(ListListlong?), ListListReadOnlyFirst arrayArrayOfModel default(ListListReadOnlyFirst)) { this.ArrayOfString arrayOfString; this.ArrayArrayOfInteger arrayArrayOfInteger; this.ArrayArrayOfModel arrayArrayOfModel; }由于属性在 OpenAPI 定义中未出现在required列表构造函数参数与属性均允许为空序列化/反序列化时无需强制填充。ToString / ToJson模型覆写了ToString()以class ArrayTest {...}形式逐行输出三个属性并提供ToJson()内部委托给JsonConvert.SerializeObject(this, Formatting.Indented)生成缩进美化后的 JSON 字符串便于调试与日志输出。值语义Equals 与 GetHashCodeEquals对每个属性采用「空值短路 SequenceEqual」策略仅当两个实例的属性都非空时才逐元素比较列表内容元素比较使用列表的相等性GetHashCode采用 unchecked 运算对非空属性以hashCode hashCode * 59 field.GetHashCode()累加。这意味着 ArrayTest 具备值语义——两个内容相同的实例视为相等适合在断言与缓存场景中使用。校验钩子IValidatableObject.Validate目前为空实现yield break属于生成的扩展点本模型无必填项与格式约束需要自定义校验时可在此处补充。生成器如何决定这些类型源码级证据类型映射并非模板硬编码而是由 swagger-codegen 的 C# 语言生成器在元模型阶段完成。相关单元测试 modules/swagger-codegen/src/test/java/io/swagger/codegen/csharp/CSharpModelTest.java 通过构造含ArrayProperty元素为StringProperty的模型断言默认情况下datatype为ListstringbaseType为ListcontainerType为arrayisContainer为true开启setUseCollection(true)后datatype变为CollectionstringsetReturnICollection(true)只影响返回值声明不改变属性datatype。这从生成器层面印证了文档表格中ListT类型的由来数组容器默认映射为System.Collections.Generic.ListT且可通过生成选项切换为CollectionT。同理long?的映射来自 OpenAPIinteger/format: int64与 C# 语言映射表的对应规则ReadOnlyFirst的引用来自$ref解析后生成器对模型依赖的收集。在 C# 中使用 ArrayTest实例化与赋值using System.Collections.Generic; using IO.Swagger.Model; var model new ArrayTest { ArrayOfString new Liststring { alpha, beta }, ArrayArrayOfInteger new ListListlong? { new Listlong? { 1L, 2L } }, ArrayArrayOfModel new ListListReadOnlyFirst { new ListReadOnlyFirst { new ReadOnlyFirst { Bar x, Baz y } } } };序列化输出调用model.ToJson()后得到示意{ array_of_string: [ alpha, beta ], array_array_of_integer: [ [ 1, 2 ] ], array_array_of_model: [ [ { bar: x, baz: y } ] ] }注意 JSON 键名与 OpenAPI 定义中的 snake_case 完全一致这正是[DataMember(Namearray_of_string)]的作用。在 API 调用中的典型用法SDK 的整体用法参见 SwaggerClientNet40/README.md先生成 DLLMac/Linux 执行/bin/sh build.shWindows 执行build.bat再引入IO.Swagger.Api、IO.Swagger.Client、IO.Swagger.Model三个命名空间模型对象可直接作为 API 方法的请求体参数如FakeApi中各类 fake endpoint 的 body 参数SDK 底层通过 RestSharp Json.NET 完成序列化与传输。跨语言一致性同一模型的其他语言形态ArrayTest 定义在多个语言 SDK 中同步生成可交叉验证映射规则的一致性Bash 版 ArrayTest.md 将类型表达为array[string]、array[array[integer]]、array[array[ReadOnlyFirst]]Eiffel 版 ARRAY_TEST.md 映射为LIST [STRING_32]、LIST [LIST [INTEGER_64]]、LIST [LIST [READ_ONLY_FIRST]]对应源码见samples/client/petstore/eiffel/src/domain/array_test.eC# 全系列变体Net35、Net40、NetCoreProject、NetStandard、WithPropertyChanged均保持ListList...结构如 SwaggerClientNetStandard。也就是说OpenAPI 中「数组的数组」这一结构是跨语言通用的各语言生成器只负责翻译为对应的容器与元素类型语义等价。模型测试骨架生成的单元测试位于 samples/client/petstore/csharp/SwaggerClientNet40/src/IO.Swagger.Test/Model/ArrayTestTests.cs采用 NUnit 编写包含ArrayTestInstanceTest、ArrayOfStringTest、ArrayArrayOfIntegerTest、ArrayArrayOfModelTest四个用例骨架分别覆盖模型实例化与三个属性的读写验证。它们以 TODO 注释形式保留实际使用时只需补充断言如实例化模型后断言属性非空、IsInstanceOfTypeArrayTest等即可接入测试套件验证反序列化与序列化行为。小结ArrayTest 是 swagger-codegen 用于验证数组类属性映射的典型样本模型它浓缩了三条可复用的工程经验一维数组OpenAPItype: arrayitems直接映射为ListT元素类型由items的type/format决定string→stringinteger/int64→long?嵌套数组items中再嵌套type: array即生成ListListT同一规则在 C#、Bash、Eiffel 等多语言生成结果中保持一致模型数组items使用$ref引用其他模型时元素类型为被引用模型类如ReadOnlyFirst生成器会自动建立模型间依赖。对需要自行编写 OpenAPI 定义的开发者而言参考 petstorefake.yaml 中 ArrayTest 的写法即可准确表达多维数组与对象数组生成出的 C# 客户端将自动获得正确的强类型属性、JSON 契约与值语义。赞分享开发工具代码生成API设计【免费下载链接】swagger-codegenswagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.项目地址https://gitcode.com/gh_mirrors/sw/swagger-codegen点击查看免费下载相关推荐swagger-codegen 生成的 C 模型文档深度解析以 Petstore 的 ArrayTest 为例掌握嵌套数组类型映射swagger codegen 生成的 C 模型文档深度解析以 Petstore 的 ArrayTest 为例掌握嵌套数组类型映射 导读 本文以 swagge开发工具代码生成API设计Swagger Codegen C 客户端 ArrayTest 模型解析数组与嵌套数组的生成与使用Swagger Codegen C 客户端 ArrayTest 模型解析数组与嵌套数组的生成与使用 导读 本文围绕 Swagger Codegen 生成的 C开发工具代码生成API设计Swagger Codegen 生成 C 模型详解ArrayTest 多维数组属性的源码级剖析Swagger Codegen 生成 C 模型详解ArrayTest 多维数组属性的源码级剖析 ArrayTest 是 Swagger Codegen 官方开发工具代码生成API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考