Carrot.Data.Scaffold.Compilers.Modules.ApiSchemas

net

Scaffold compiler module that generates Postman Collection JSON files from the ScaffoldApi graph, providing ready-to-import API schema documentation.

Installation

<ProjectReference Include="..\Carrot.Data.Scaffold.Compilers.Modules.ApiSchemas\Carrot.Data.Scaffold.Compilers.Modules.ApiSchemas.csproj" />

Architecture

Compiler Module

ScaffoldCompilerApiSchemas extends ScaffoldCompilerModule<ScaffoldApi, ScaffoldCompilerApiSchemasOptions>. For each API in the scaffold graph, it registers a single ScaffoldCompilerApiSchemasRendererApi instance.

Postman Collection Generation

The renderer builds a PostmanCollection (from Carrot.Data.Formats.Postman) for each API:

1. Creates a collection named "Carrot API: {ApiName}" with a deterministic GUID derived from CarrotId.FromString
2. For each controller, creates a PostmanItemFolder
3. For each action, creates a PostmanItemRequest with:
   • HTTP verb and URL (using variable + resolved route)
   • Content-Type: application/json header for verbs supporting request bodies
   • Accept: application/json header for verbs expecting response bodies
   • Request body properties mapped from scaffold model or command properties

Property Type Mapping

ConvertPropertyCore maps CLR types to Postman body property types:

CLR Type	Postman Type
string, Guid	String
int, long, short	Int
float, double, decimal	Float
bool	Bool
DateTime, *Instant*	DateTime
Enums	String
Arrays	Array
Everything else	Object

Output Structure

Platform/Api/{Collection}/
  Carrot.Platform.Api.{Collection}.{Api}.Models/
    schemas/
      collection.json    # Postman Collection v2.1

Dependencies

Dependency	Kind
Carrot.Data.Scaffold.Compilers	project (scaffold compiler framework)
Carrot.Data.Formats.Postman	project (Postman collection data model)

Build

dotnet build

Targets net10.0.

---

Usage Guide

Generate Postman Collection JSON files from a scaffold API definition for API documentation and testing.

Getting Started

Register the ApiSchemas module on a scaffold compiler:

IScaffoldCompiler compiler = scaffold.CreateCompiler()
    .AddModuleApiSchemas();

Typically used alongside the Api module:

IScaffoldCompiler compiler = scaffold.CreateCompiler()
    .AddModuleApi()
    .AddModuleApiSchemas();

Then compile:

IScaffoldCompilerResult result = compiler.Compile();

Common Patterns

Generated Postman Collection Structure

Each API produces a Postman Collection JSON with:

Carrot API: {ApiName}
  |-- {ControllerName}/
  |     |-- GetAll    (GET  /api/v1/{collection}/{resource})
  |     |-- GetById   (GET  /api/v1/{collection}/{resource}/{id})
  |     |-- Create    (POST /api/v1/{collection}/{resource})
  |     ...
  |-- {AnotherController}/
        ...

Importing into Postman

The generated collection.json can be imported directly into Postman via File > Import, or used with Newman for CI testing:

newman run schemas/collection.json --env-var "baseUrl=https://localhost:5001"

Request Body Generation

For actions that accept a request body (POST, PUT, PATCH), the collection includes typed property definitions derived from scaffold models and commands. Properties include display names, JSON property names, types, and required flags.

Tips

• The variable must be set in your Postman environment to point at your running API instance.
• Collection IDs are deterministic - re-running the scaffold produces the same GUIDs, so re-importing won't create duplicates in Postman.
• Only models and commands referenced by controller actions get their properties included in request bodies.