Momentum.ServiceDefaults.Api 0.0.9

Momentum.ServiceDefaults.Api

API-specific service defaults for Momentum platform extending the base ServiceDefaults with gRPC, OpenAPI documentation (Scalar), and API-focused configurations. Essential for Momentum API projects.

Overview

The Momentum.ServiceDefaults.Api package extends Momentum.ServiceDefaults with additional configurations specifically designed for API projects. It provides comprehensive support for both REST and gRPC APIs, along with modern documentation tools.

Installation

Add the package to your project using the .NET CLI:

dotnet add package Momentum.ServiceDefaults.Api

Or using the Package Manager Console:

Install-Package Momentum.ServiceDefaults.Api

Key Features

• All ServiceDefaults Features: Inherits complete observability, messaging, and database capabilities
• gRPC Support: Full gRPC server configuration with reflection and web support
• OpenAPI Integration: Automatic OpenAPI 3.0 specification generation
• Scalar Documentation: Modern, interactive API documentation interface
• Enhanced Telemetry: API-specific metrics, tracing, and monitoring

Getting Started

Prerequisites

• .NET 10.0 or later
• ASP.NET Core 9.0 or later
• All prerequisites from Momentum.ServiceDefaults

Basic Usage

REST API Example

// Program.cs
using Momentum.ServiceDefaults.Api;
using Momentum.ServiceDefaults.Api.OpenApi.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Add API service defaults - includes all base features plus API-specific configurations
builder.AddApiServiceDefaults();

// Configure OpenAPI with .NET 10 native support and XML documentation
// NOTE: AddOpenApi must be called directly in the API project (not in a library)
// for the .NET 10 source generator to intercept it and generate XML documentation
builder.Services.AddOpenApi(options => options.ConfigureOpenApiDefaults());

var app = builder.Build();

// Configure API defaults (routing, auth, OpenAPI endpoints, etc.)
app.ConfigureApiUsingDefaults();

app.Run();

gRPC Service Example

// Program.cs
using Momentum.ServiceDefaults.Api;
using Momentum.ServiceDefaults.Api.OpenApi.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.AddApiServiceDefaults();
builder.Services.AddOpenApi(options => options.ConfigureOpenApiDefaults());

var app = builder.Build();

app.ConfigureApiUsingDefaults();

// Map gRPC services
app.MapGrpcService<UserService>();
app.MapGrpcService<OrderService>();

app.Run();

Hybrid API (REST + gRPC)

// Program.cs
using Momentum.ServiceDefaults.Api;
using Momentum.ServiceDefaults.Api.OpenApi.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.AddApiServiceDefaults();
builder.Services.AddOpenApi(options => options.ConfigureOpenApiDefaults());

var app = builder.Build();

app.ConfigureApiUsingDefaults();

// Map additional gRPC services
app.MapGrpcService<UserService>();

app.Run();

What Gets Configured

In addition to all Momentum.ServiceDefaults features, this package automatically configures:

1. gRPC Services

• gRPC Server: Full ASP.NET Core gRPC support
• Server Reflection: gRPC reflection for tool support
• gRPC-Web: Browser-compatible gRPC over HTTP

2. OpenAPI Documentation

• Specification Generation: Automatic OpenAPI 3.0 spec generation
• Endpoint Discovery: Automatic API endpoint documentation
• Schema Generation: Request/response model documentation

3. Scalar API Documentation

• Interactive UI: Modern API documentation interface
• Try It Out: Built-in API testing capabilities
• Automatic Discovery: Works with your OpenAPI specification

4. Enhanced Observability

• gRPC Telemetry: Metrics and tracing for gRPC calls
• API Metrics: Request rates, latencies, and error rates
• Documentation Metrics: API documentation usage tracking

Available Endpoints

When you call app.ConfigureApiUsingDefaults(), in development you get:

Configuration

OpenAPI Settings

// appsettings.json
{
    "OpenApi": {
        "Document": {
            "Title": "My API",
            "Version": "v1",
            "Description": "API for my application"
        }
    }
}

gRPC Configuration

// appsettings.json
{
    "Grpc": {
        "EnableDetailedErrors": true,
        "MaxReceiveMessageSize": 4194304,
        "MaxSendMessageSize": 4194304
    }
}

Advanced Usage

Custom OpenAPI Configuration

using Momentum.ServiceDefaults.Api;
using Momentum.ServiceDefaults.Api.OpenApi.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.AddApiServiceDefaults();

// Configure OpenAPI with custom transformers
builder.Services.AddOpenApi(options =>
{
    // Apply Momentum defaults (server URL normalization, etc.)
    options.ConfigureOpenApiDefaults();

    // Add custom document transformers
    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info.Contact = new() { Name = "Support", Email = "support@company.com" };
        return Task.CompletedTask;
    });
});

Custom gRPC Configuration

using Momentum.ServiceDefaults.Api;

var builder = WebApplication.CreateBuilder(args);

builder.AddApiServiceDefaults();

// Customize gRPC services (overrides defaults)
builder.Services.AddGrpc(options =>
{
    options.EnableDetailedErrors = true;
    options.MaxReceiveMessageSize = 8 * 1024 * 1024; // 8MB
});

Integrated Dependencies

This package includes:

Note: For XML documentation in OpenAPI, ensure your project has <GenerateDocumentationFile>true</GenerateDocumentationFile> and enable the OpenAPI source generator interceptors with:

<InterceptorsNamespaces>$(InterceptorsNamespaces);Microsoft.AspNetCore.OpenApi.Generated</InterceptorsNamespaces>

Target Frameworks

• .NET 10.0: Primary target framework
• ASP.NET Core 9.0: Includes framework reference

Use Cases

This package is ideal for:

• REST APIs: Traditional HTTP APIs with OpenAPI documentation
• gRPC Services: High-performance RPC services
• Hybrid APIs: Services supporting both REST and gRPC protocols
• API Gateways: Services that aggregate other APIs
• Microservice APIs: Services in event-driven architectures

Related Packages

• Momentum.ServiceDefaults - Base service configuration
• Momentum.Extensions.Messaging.Kafka - Kafka messaging
• Momentum.Extensions.Abstractions - Core abstractions

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

For contribution guidelines and more information about the Momentum platform, visit the main repository.