class、record、struct で書いた C# のモデルを貼り付けると、System.Text.Json と Newtonsoft.Json のルールに従った例の JSON ドキュメントが得られます。命名ポリシーは ASP.NET Core が既定で使う camelCase と、書かれたとおりのプロパティ名から選べます。[JsonPropertyName] や [JsonProperty] で指定した名前は常に優先されます。
Web API のリクエスト/レスポンスモデルからフロントエンドや外部パートナーにサンプルを渡すとき、Swagger(Swashbuckle)の例を埋めるとき、HttpClient を使った結合テストのボディを用意するときに使えます。
using、namespace、コンストラクター、メソッドは残したままで構いません。命名ポリシー を選びます。標準的な Web API プロジェクトなら camelCase(ASP.NET Core の既定)、PropertyNamingPolicy = null を設定している場合や Newtonsoft の既定に頼っている場合は プロパティ名のまま です。ルート型 が 自動 のときは、他のモデルから参照されていない最初の型がルートになります。必要ならリストから変更してください。.http ファイル、xUnit のリクエストボディに使います。オプションの選択は URL に保存されます。public class InventoryItem
{
public Guid Id { get; set; }
public string SKU { get; set; } = "";
[JsonPropertyName("stock_qty")]
public int StockQuantity { get; set; }
public StockState State { get; set; } = StockState.InStock;
public DateTimeOffset UpdatedAt { get; set; }
public List<string> Barcodes { get; set; } = new();
[JsonIgnore]
public string WarehouseNote { get; set; } = "";
private int _version;
}
public enum StockState { InStock, LowStock, OutOfStock }{
"id": "00000000-0000-0000-0000-000000000000",
"sku": "",
"stock_qty": 0,
"state": 0,
"updatedAt": "1970-01-01T00:00:00+00:00",
"barcodes": [
""
]
}camelCase ポリシーでは SKU のような全大文字の名前は sku になり、System.Text.Json の JsonNamingPolicy.CamelCase と一致します。一方 [JsonPropertyName("stock_qty")] はポリシーに関係なくその名前のままです。WarehouseNote([JsonIgnore])と private フィールドの _version は除外されます。enum の State には文字列コンバーターがないため、初期化子 StockState.InStock の数値である 0 が表示されます。
[JsonPropertyName]、Newtonsoft の [JsonProperty]、そして [DataMember(Name = ...)]。public なプロパティとフィールド、および [JsonInclude] を付けた非 public メンバーだけです。static、const、[JsonIgnore]、[IgnoreDataMember] は除外され、Condition = WhenWritingNull のような条件付きの除外は残ります。record Customer(long Id, string Name))と [property: JsonPropertyName(...)] のターゲット指定に対応しています。=> ...)も、System.Text.Json がシリアライズするのと同じように含まれます。= 10 のような明示的な値も反映)。enum かプロパティに [JsonConverter(typeof(JsonStringEnumConverter))](または Newtonsoft の StringEnumConverter)がある場合や、メンバーに [JsonStringEnumMemberName] / [EnumMember(Value = ...)] がある場合は名前の文字列を使います。DateTime → 1970-01-01T00:00:00、DateTimeOffset → 1970-01-01T00:00:00+00:00、DateOnly → 1970-01-01、TimeOnly/TimeSpan → 00:00:00、Guid → すべてゼロの GUID。int?/Nullable<T> は内側の型を使い、List<T>/IEnumerable<T>/配列は要素を1つ持ち、Dictionary<int, V> は "0" をキーにし、object、JsonElement、JObject は null になります。= 1.5、= "KRW")はサンプル値として使います。[JsonPropertyName] と既定の命名が混ざった DTO では、Swagger UI が自動生成する例を読み違えやすくなります。この出力を ISchemaFilter や XML の <example> コメントに使えば、ドキュメントとレスポンスのキーがそろいます。
同じモデルで 命名ポリシー を切り替えて、移行後にキーの大文字・小文字がどう変わるかを事前に確認できます。
クライアントとサーバーがモデルを別々に持っている場合、それぞれから JSON を生成して比べれば、キー名の食い違いをすぐに見つけられます。
Program.cs の AddJsonOptions でグローバルに登録した JsonStringEnumConverter はモデルのコードからは見えないため、enum は数値のまま出力されます。名前で見たい場合は、貼り付ける前に enum の宣言へ [JsonConverter(typeof(JsonStringEnumConverter))] を付けてください。string? のような null 許容参照型には、null ではなく型に応じたサンプル値が入ります。[JsonConverter] 属性、JsonSerializerOptions の DefaultIgnoreCondition、snake_case ポリシー(JsonNamingPolicy.SnakeCaseLower)は反映されません。[JsonPolymorphic]/[JsonDerivedType] によるポリモーフィズムには対応しておらず、宣言された基底型だけが生成されます。命名ポリシー の各オプションはどんなときに使いますか?ASP.NET Core Web API は camelCase の JsonSerializerDefaults.Web を使います。オプションなしで JsonSerializer.Serialize を呼ぶコンソールアプリや、既定設定の Newtonsoft.Json はプロパティ名をそのまま使うので、その場合は プロパティ名のまま を選んでください。
public string FullName => ... のような計算プロパティが出てくるのはなぜですか?System.Text.Json も Newtonsoft.Json も getter を持つ public プロパティをシリアライズするため、計算プロパティもレスポンスに含まれます。出力したくない場合は [JsonIgnore] を付けてください。
[JsonPropertyName] が、実行時にキー名を変えてくれません。ターゲットを指定しないと、コンパイラーは属性をコンストラクターのパラメーターにだけ適用します。このツールはどちらの書き方も認識しますが、シリアライズされるプロパティの名前を確実に変えるには [property: JsonPropertyName("...")] と書いてください。
DateTime の値に Z が付かないのはなぜですか?DateTimeKind.Unspecified の DateTime はオフセットなしでシリアライズされます。UTC のオフセットを明示したい場合は、DateTimeOffset を使えば +00:00 形式になります。