MinAPI.Templates 1.0.0

MinAPI - Plantilla de Minimal API con .NET Core

Plantilla preconfigurada para crear APIs REST con .NET 10, PostgreSQL, Entity Framework Core y Swagger.

👨‍🏫 Autor

Bryan Iban Mamani Quispe

- Página Oficial del Proyecto

- Mi Página Oficial

Creado para el Curso de Blazor + .NET Core en la Sociedad Científica de la Universidad Privada del Valle - La Paz

🚀 Instalación

dotnet new install MinAPI.Template
dotnet new minapi -n MiProyecto
cd MiProyecto
dotnet run

📁 Estructura del Proyecto

minapi/
├── Database/           # Contexto de Entity Framework
├── Endpoints/          # Definición de endpoints agrupados
├── Handlers/           # Extensiones para registro automático
├── Models/             # (Crear aquí tus modelos)
├── Services/           # (Crear aquí tus servicios)
└── Program.cs          # Configuración principal

🔥 Características

• ✅ Registro automático de servicios con convención IServicioService → ServicioService
• ✅ Mapeo automático de endpoints con convención *Endpoints.cs
• ✅ PostgreSQL preconfigurado con Entity Framework Core
• ✅ Swagger con redirección automática en desarrollo
• ✅ Documentación XML completa en todo el código

📝 Guía de Uso

1. Configurar la Base de Datos

Edita appsettings.json:

{
  "ConnectionStrings": {
    "DbConnectionString": "Host=localhost;Database=midb;Username=postgres;Password=mipassword"
  }
}

2. Crear un Modelo

// Models/Usuario.cs
public class Usuario
{
    public int Id { get; set; }
    public string Nombre { get; set; }
}

3. Agregar DbSet al Contexto

// Database/PostgreDbContext.cs
public DbSet<Usuario> Usuarios => Set<Usuario>();

4. Crear un Servicio

// Services/IUsuarioService.cs
public interface IUsuarioService
{
    Task<List<Usuario>> ObtenerTodos();
    Task<Usuario?> ObtenerPorId(int id);
    Task<Usuario> Crear(Usuario usuario);
}

// Services/UsuarioService.cs
public class UsuarioService : IUsuarioService
{
    private readonly PostgreDbContext _context;

    public UsuarioService(PostgreDbContext context)
    {
        _context = context;
    }

    public async Task<List<Usuario>> ObtenerTodos()
    {
        return await _context.Usuarios.ToListAsync();
    }

    public async Task<Usuario?> ObtenerPorId(int id)
    {
        return await _context.Usuarios.FindAsync(id);
    }

    public async Task<Usuario> Crear(Usuario usuario)
    {
        _context.Usuarios.Add(usuario);
        await _context.SaveChangesAsync();
        return usuario;
    }
}

5. Crear Endpoints (usando el servicio)

// Endpoints/UsuarioEndpoints.cs
public class UsuarioEndpoints
{
    public UsuarioEndpoints(WebApplication app)
    {
        var grupo = app.MapGroup("/api/usuarios").WithTags("Usuarios");

        grupo.MapGet("", async (IUsuarioService service) =>
        {
            var usuarios = await service.ObtenerTodos();
            return Results.Ok(usuarios);
        })
        .WithName("ObtenerUsuarios")
        .Produces<List<Usuario>>(StatusCodes.Status200OK);

        grupo.MapGet("{id:int}", async (int id, IUsuarioService service) =>
        {
            var usuario = await service.ObtenerPorId(id);
            return usuario is not null
                ? Results.Ok(usuario)
                : Results.NotFound();
        })
        .WithName("ObtenerUsuarioPorId")
        .Produces<Usuario>(StatusCodes.Status200OK)
        .Produces(StatusCodes.Status404NotFound);

        grupo.MapPost("", async (Usuario usuario, IUsuarioService service) =>
        {
            var nuevoUsuario = await service.Crear(usuario);
            return Results.Created($"/api/usuarios/{nuevoUsuario.Id}", nuevoUsuario);
        })
        .WithName("CrearUsuario")
        .Produces<Usuario>(StatusCodes.Status201Created);
    }
}

6. Ejecutar Migraciones

dotnet ef migrations add InitialCreate
dotnet ef database update

🎓 Convenciones Importantes

Servicios (Registro Automático con Scoped)

• Interfaz: I[Nombre]Service.cs (ej: IUsuarioService)
• Clase: [Nombre]Service.cs (ej: UsuarioService)
• Se registran automáticamente al iniciar la aplicación

Endpoints (Instanciación Automática)

• Clase: [Nombre]Endpoints.cs (ej: UsuarioEndpoints)
• Constructor: Debe recibir WebApplication app
• Inyección: Usa interfaces de servicios en los parámetros de los endpoints

⚠️ Importante

Los endpoints NO deben inyectar PostgreDbContext directamente. Siempre usa servicios:

// ❌ MAL - No hagas esto
grupo.MapGet("", async (PostgreDbContext db) => { ... });

// ✅ BIEN - Usa servicios
grupo.MapGet("", async (IUsuarioService service) => { ... });

🏗️ Arquitectura Recomendada

Cliente (HTTP Request)
    ↓
Endpoint (UsuarioEndpoints.cs)
    ↓
Servicio (IUsuarioService → UsuarioService)
    ↓
DbContext (PostgreDbContext)
    ↓
Base de Datos (PostgreSQL)

📚 Recursos

• Documentación de Minimal APIs
• Entity Framework Core
• Npgsql (PostgreSQL)
• Inyección de Dependencias