Unitegra.ApiMetadata 1.5.0

Unitegra.ApiMetadata

NuGet balíček pro automatickou extrakci metadat z API endpointů pro Unitegra dokumentaci.

Instalace

dotnet add package Unitegra.ApiMetadata

Nebo přidáním reference v .csproj:

<PackageReference Include="Unitegra.ApiMetadata" Version="1.5.0" />

Použití

1. Konfigurace v appsettings.json

{
  "UnitegraMetadata": {
    "Secret": "<your-secret-here>",
    "IntegrationName": "HegerAPI",
    "CacheDurationMinutes": 30
  }
}

2. Registrace služeb v Program.cs / Startup.cs

using Unitegra.ApiMetadata.Extensions;

// .NET 6+ (Program.cs)
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddUnitegraMetadata(builder.Configuration.GetSection("UnitegraMetadata"));

// .NET Core 3.1 / .NET 5 (Startup.cs)
public void ConfigureServices(IServiceCollection services)
{
    services.AddUnitegraMetadata(Configuration.GetSection("UnitegraMetadata"));
}

Alternativně lze konfigurovat přímo v kódu:

builder.Services.AddUnitegraMetadata(options =>
{
    options.Secret = "<your-secret-here>";
    options.IntegrationName = "Moje API";
    options.CacheDurationMinutes = 60;
});

3. Označení endpointů atributem

using Unitegra.ApiMetadata.Attributes;

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    // GET endpoint = Source (čte data)
    [HttpGet]
    [EndpointMetadata(typeof(Product))]
    public async Task<List<Product>> GetProducts()
    {
        // implementace
    }

    // POST endpoint = Target (zapisuje data)
    [HttpPost]
    [EndpointMetadata(typeof(Product))]
    public async Task<IActionResult> CreateProduct([FromBody] Product product)
    {
        // implementace
    }

    // S popisem a tagy
    [HttpPut("{id}")]
    [EndpointMetadata(typeof(Product), Description = "Aktualizace produktu", Tags = new[] { "products", "update" })]
    public async Task<IActionResult> UpdateProduct(int id, [FromBody] Product product)
    {
        // implementace
    }
}

4. Více entit v jednom endpointu (TargetTypes)

[HttpPost]
[EndpointMetadata(typeof(Order), typeof(OrderItem))]
public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
{
    // implementace
}

Endpoint pro metadata

Po registraci služeb bude dostupný endpoint:

GET /api/unitegra-metadata/endpoints
Header: X-Api-Key: <your-secret-here>

Odpověď

{
  "integrationName": "Moje API",
  "mappings": [
    {
      "source": {
        "server": "sql-server-name",
        "database": "MyDatabase",
        "entity": "dbo.Products"
      },
      "target": {
        "server": "Moje API",
        "database": "API",
        "entity": "GET /api/products"
      },
      "columnMapping": [
        {
          "source": { "column": "Id", "type": "int" },
          "target": { "column": "Id", "type": "int" }
        },
        {
          "source": { "column": "Name", "type": "nvarchar" },
          "target": { "column": "Name", "type": "nvarchar" }
        }
      ]
    }
  ]
}

Další endpointy

• GET /api/unitegra-metadata/endpoints/raw (header X-Api-Key) - Raw metadata (pro debugging)
• GET /api/unitegra-metadata/health - Health check (bez autentizace)

Konfigurace

Jak to funguje

1. Balíček prohledá assembly pomocí reflexe
2. Najde všechny controller metody s atributem [EndpointMetadata]
3. Pro každý entity typ zkusí najít metadata v registrovaných DbContext
4. Pokud DbContext neexistuje, vytvoří základní metadata z typu
5. Vygeneruje mappingy ve formátu kompatibilním s Unitegra

Explicitní mapování sloupců

MapColumn - explicitní mapování

Pokud se názvy sloupců liší mezi DTO a entitou, použijte [MapColumn]:

[HttpPost]
[EndpointMetadata(
    SourceType = typeof(InvoiceDTO),
    TargetTypes = new[] { typeof(Invoice), typeof(User) },
    Description = "Import faktur")]
// Mapování pro entitu Invoice
[MapColumn("BankPaymentIdentification", "Id", TargetType = typeof(Invoice))]
// Mapování pro entitu User (z vnořeného UserDTO)
[MapColumn("UserId", "Id", TargetType = typeof(User), SourceType = typeof(UserDTO))]
[MapColumn("FirstName", "FirstName", TargetType = typeof(User), SourceType = typeof(UserDTO))]
public async Task<IActionResult> PostInvoices(List<InvoiceDTO> invoices)

IgnoreColumn - ignorování sloupců

Pro sloupce, které se nemají mapovat (computed columns, navigation properties):

[HttpPost]
[EndpointMetadata(SourceType = typeof(ProductDTO), TargetTypes = new[] { typeof(Product) })]
[IgnoreColumn("SynchronizationStatus", TargetType = typeof(Product))]
[IgnoreColumn("SynchronizationStatusMessage", TargetType = typeof(Product))]
public async Task<IActionResult> PostProducts(List<ProductDTO> products)

Automatická detekce vnořených DTO (v1.3.0+)

Od verze 1.3.0 knihovna automaticky detekuje vnořené DTO objekty:

// InvoiceDTO obsahuje vnořené objekty:
public class InvoiceDTO
{
    public string InvoiceId { get; set; }
    public UserDTO User { get; set; }           // Vnořený objekt
    public List<InvoiceItemDTO> Items { get; set; }  // Kolekce
}

// Knihovna automaticky najde:
// - UserDTO pro target entitu User
// - InvoiceItemDTO pro target entitu InvoiceItem
// Není potřeba explicitní MapColumn pro všechny properties

Automatická detekce funguje pro:

• Kolekce (List<T>, IEnumerable<T>, pole)
• Vnořené objekty (single properties jako User typu UserDTO)
• Rekurzivní hledání (1 úroveň do hloubky)

Mapování probíhá podle normalizovaného názvu (odstraní se sufixy Dto, Entity, Model, Post, Get, Request, Response).

Integrace s EF Core

Pokud vaše API používá Entity Framework Core, balíček automaticky:

• Najde název tabulky a schématu
• Extrahuje server a databázi z connection stringu
• Získá informace o sloupcích včetně datových typů