C# クラスを JSON に変換しよう!

C# の class·record コードを入力すると例の JSON を作ります!System.Text.Json [JsonPropertyName], Newtonsoft.Json [JsonProperty] 対応。API ドキュメントやテスト用のリクエストボディ(sample JSON)に。
C#
結果
 

C# クラスを JSON に変換しよう!

class、record、struct で書いた C# のモデルを貼り付けると、System.Text.Json と Newtonsoft.Json のルールに従った例の JSON ドキュメントが得られます。命名ポリシーは ASP.NET Core が既定で使う camelCase と、書かれたとおりのプロパティ名から選べます。[JsonPropertyName] や [JsonProperty] で指定した名前は常に優先されます。

Web API のリクエスト/レスポンスモデルからフロントエンドや外部パートナーにサンプルを渡すとき、Swagger(Swashbuckle)の例を埋めるとき、HttpClient を使った結合テストのボディを用意するときに使えます。

使い方

  1. モデルのソースを貼り付けます。using、namespace、コンストラクター、メソッドは残したままで構いません。
  2. 命名ポリシー を選びます。標準的な Web API プロジェクトなら camelCase(ASP.NET Core の既定)、PropertyNamingPolicy = null を設定している場合や Newtonsoft の既定に頼っている場合は プロパティ名のまま です。
  3. ルート型 が 自動 のときは、他のモデルから参照されていない最初の型がルートになります。必要ならリストから変更してください。
  4. JSON をコピーして、Swagger の例、.http ファイル、xUnit のリクエストボディに使います。オプションの選択は URL に保存されます。

例

入力 (C#)
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 }
出力 (JSON · camelCase)
{
  "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 が表示されます。

対応機能

  • 名前を変える属性: System.Text.Json の [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 がシリアライズするのと同じように含まれます。
  • enum は System.Text.Json と Newtonsoft の既定どおり数値で出力します(= 10 のような明示的な値も反映)。enum かプロパティに [JsonConverter(typeof(JsonStringEnumConverter))](または Newtonsoft の StringEnumConverter)がある場合や、メンバーに [JsonStringEnumMemberName] / [EnumMember(Value = ...)] がある場合は名前の文字列を使います。
  • 日付と ID: 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")はサンプル値として使います。

利用シーン

Swashbuckle の例を実際のレスポンスに合わせる

[JsonPropertyName] と既定の命名が混ざった DTO では、Swagger UI が自動生成する例を読み違えやすくなります。この出力を ISchemaFilter や XML の <example> コメントに使えば、ドキュメントとレスポンスのキーがそろいます。

Newtonsoft から System.Text.Json への移行

同じモデルで 命名ポリシー を切り替えて、移行後にキーの大文字・小文字がどう変わるかを事前に確認できます。

Unity/MAUI クライアントとサーバー間の契約の確認

クライアントとサーバーがモデルを別々に持っている場合、それぞれから JSON を生成して比べれば、キー名の食い違いをすぐに見つけられます。

注意点と制限

  • Program.cs の AddJsonOptions でグローバルに登録した JsonStringEnumConverter はモデルのコードからは見えないため、enum は数値のまま出力されます。名前で見たい場合は、貼り付ける前に enum の宣言へ [JsonConverter(typeof(JsonStringEnumConverter))] を付けてください。
  • string? のような null 許容参照型には、null ではなく型に応じたサンプル値が入ります。
  • enum 文字列コンバーター以外のカスタム [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] を付けてください。

record の位置指定パラメーターに付けた [JsonPropertyName] が、実行時にキー名を変えてくれません。

ターゲットを指定しないと、コンパイラーは属性をコンストラクターのパラメーターにだけ適用します。このツールはどちらの書き方も認識しますが、シリアライズされるプロパティの名前を確実に変えるには [property: JsonPropertyName("...")] と書いてください。

DateTime の値に Z が付かないのはなぜですか?

DateTimeKind.Unspecified の DateTime はオフセットなしでシリアライズされます。UTC のオフセットを明示したい場合は、DateTimeOffset を使えば +00:00 形式になります。