Skip to content

biellts/universidade-automatiza / .claude/skills/backend-criar-endpoint-minimal-api

backend-criar-endpoint-minimal-api

Verified

Cria um endpoint Minimal API no padrão IUseCaseEndpoint do projeto. Use este skill quando solicitado a criar um novo endpoint HTTP, rota, controller ou API para um caso de uso.

FileKindSize
SKILL.mdskill md7.5 KB
---
name: backend-criar-endpoint-minimal-api
description: Cria um endpoint Minimal API no padrão IUseCaseEndpoint do projeto. Use este skill quando solicitado a criar um novo endpoint HTTP, rota, controller ou API para um caso de uso.
---

Para criar um novo endpoint Minimal API neste projeto, siga o processo abaixo:

## 1. Localização

Crie o arquivo em:
```
src/apps/Automatiza.Modules.{Modulo}/Features/{Entidade}s/UseCases/{NomeDoCasoDeUso}/{X}Endpoint.cs
```

Os exemplos usam o módulo Catálogo (`{Modulo}` = `Catalogo`).

## 2. Estrutura do endpoint

Endpoint real `CriarTrilhaEndpoint`:

```csharp
namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.CriarTrilha;

public class CriarTrilhaEndpoint : IUseCaseEndpoint
{
    public static RouteHandlerBuilder Map(IEndpointRouteBuilder app)
    {
        return app.MapPost("/admin/tracks", async (
            CriarTrilhaRequest request,
            [FromServices] IDispatcher dispatcher,
            CancellationToken cancellationToken) =>
        {
            var result = await dispatcher.Send(request, cancellationToken);

            return result.TryGetValue(out var criada)
                ? Results.Created($"/api/v1/admin/tracks/{criada.Id}", criada)
                : Results.BadRequest(result.Errors);
        })
        .WithSummary("Criar trilha")
        .WithDescription("Cadastra uma trilha no catálogo. Cursos, módulos e aulas entram nas próximas features.")
        .Produces<CriarTrilhaResponse>(StatusCodes.Status201Created);
    }
}
```

Leitura por Id (`ObterTrilhaPorIdEndpoint`) — o handler devolve erro quando não acha, e o endpoint traduz para `404`:

```csharp
return app.MapGet("/admin/tracks/{id:guid}", async (
    Guid id,
    [FromServices] IDispatcher dispatcher,
    CancellationToken cancellationToken) =>
{
    var result = await dispatcher.Send(new ObterTrilhaPorIdRequest(id), cancellationToken);

    return result.TryGetValue(out var trilha)
        ? Results.Ok(trilha)
        : Results.NotFound(result.Errors);
})
.WithSummary("Obter trilha")
.Produces<ObterTrilhaPorIdResponse>()
.Produces<IEnumerable<Error>>(StatusCodes.Status404NotFound);
```

Listagem (`ListarTrilhasEndpoint`) recebe filtros e paginação pela query string com `[AsParameters] ListarTrilhasRequest request` e declara `.Produces<PaginatedResponse<ListarTrilhasItemResponse>>()`.

### O que o `MapEndoints` já documenta para você

Não repita no endpoint: o `MapEndoints` aplica em todas as rotas o `operationId`
(nome da classe sem o sufixo `Endpoint`), o `400` tipado com `IEnumerable<Error>` e o `401`.
Declare no endpoint **só** o que é seu:

| Situação | O que declarar |
|---|---|
| Devolve corpo | `.Produces<TResponse>()` |
| Devolve `Results.NoContent()` | `.Produces(StatusCodes.Status204NoContent)` |
| Devolve `Results.Ok()` sem corpo | `.Produces(StatusCodes.Status200OK)` |
| Devolve `Results.Created(...)` | `.Produces<TResponse>(StatusCodes.Status201Created)` |
| Devolve `Results.NotFound(result.Errors)` | `.Produces<IEnumerable<Error>>(StatusCodes.Status404NotFound)` |
| Devolve arquivo / stream | `.Produces(StatusCodes.Status200OK, contentType: "...")` — um por content type possível |

Sem a resposta de sucesso declarada, o endpoint aparece no Scalar **só com os
erros**, como se nunca funcionasse. E cuidado com a ordem: um `.Produces(200)` sem
tipo depois de um `.Produces<T>()` **apaga** o schema do anterior.

## 3. Rotas e métodos HTTP

As rotas ficam em **inglês, no plural**, como na arquitetura (`/admin/tracks`, `/me/certificates`), e são escritas inteiras no endpoint; o prefixo `api/v1` vem do grupo do módulo. O `Location` do `Created` leva o caminho completo (`/api/v1/...`).

| Operação | Método |
|---|---|
| Criar recurso | `MapPost("/admin/tracks")` |
| Atualizar recurso completo | `MapPut("/admin/tracks/{id:guid}")` |
| Atualizar parcialmente | `MapPatch("/admin/tracks/{id:guid}")` |
| Remover recurso | `MapDelete("/admin/tracks/{id:guid}")` |
| Obter por ID | `MapGet("/admin/tracks/{id:guid}")` |
| Listar / paginar | `MapGet("/admin/tracks")` |

Os Ids são `Guid`: use a restrição `{id:guid}` na rota.

## 4. Registro no ModuleConfiguration

`MapDocumentedGroup` exige o grupo de documentação (`GruposDeDocumentacao`) como terceiro
argumento; o `TagGroupsDocumentTransformer` usa esse grupo para agrupar a navegação do
Scalar (`x-tagGroups`). Assinatura real em `EndpointDiscover.cs`:

```csharp
MapDocumentedGroup(this IEndpointRouteBuilder app, string prefix, string tag, string grupoDeDocumentacao)
```

Cada módulo registra um único grupo para todo o seu `Features` em `ModuleConfiguration.cs`. No
Catálogo:

```csharp
public static IEndpointRouteBuilder MapCatalogoEndpoints(this IEndpointRouteBuilder endpoints)
{
    // Sem autorização até o módulo Identidade existir (Fase 1, item 2): não publicar fora do ambiente local.
    endpoints
        .MapDocumentedGroup(PrefixUri, "Catálogo", GruposDeDocumentacao.Catalogo)
        .MapEndoints("Automatiza.Modules.Catalogo.Features", typeof(ModuleConfiguration).Assembly);

    return endpoints;
}
```

Um caso de uso novo dentro de `Features/{Entidade}s/...` **não precisa** de um novo registro:
`MapEndoints` descobre qualquer `IUseCaseEndpoint` cujo namespace comece com
`Automatiza.Modules.{Modulo}.Features` e já o mapeia dentro desse grupo único. Só adicione
uma chamada extra a `MapDocumentedGroup`/`MapEndoints` se o caso de uso exigir um prefixo de
rota ou uma tag do Scalar diferentes do restante do módulo — sempre passando a constante de
`GruposDeDocumentacao` do módulo como terceiro argumento.
Módulo novo cria a sua constante em `GruposDeDocumentacao` (`src/apps/Automatiza.CrossCutting/Modules/OpenApiTagGroups.cs`) — ver a skill `backend-criar-modulo`.

## 5. Autorização

O módulo Identidade ainda não existe (Fase 1, item 2): por isso o grupo usa `MapDocumentedGroup`,
sem política. Não invente claims, políticas ou constantes de autorização. Quando a Identidade
existir, `MapAuthorizedGroup`/`MapPublicGroup` (mesma assinatura de três argumentos) passam a ser
usados e esta seção deve ser revisada. Até lá, nenhum endpoint é publicado fora do ambiente local.

Mesmo sem autenticação, o que vale ponto é decidido no servidor: nenhum endpoint devolve gabarito
ao navegador nem aceita nota, XP ou "concluído" calculados pelo cliente.

## 6. Regras obrigatórias

- Toda classe de endpoint implementa `IUseCaseEndpoint` com `public static RouteHandlerBuilder Map(IEndpointRouteBuilder app)`.
- Nunca coloque lógica de negócio no endpoint — apenas despacha via `dispatcher.Send(request, cancellationToken)`.
- Sucesso conforme a semântica (`Ok`, `Created`, `NoContent`, `NotFound` — tabela acima); erro de negócio retorna `Results.BadRequest(result.Errors)`.
- Corpo de POST/PUT/PATCH: o record do request como parâmetro (inferido do corpo). GET com filtros: `[AsParameters]`. Id na rota: parâmetro `Guid id`.
- Enums trafegam pelo nome no JSON (`"Cliente"`), via `JsonStringEnumConverter` já configurado no host.
- Sempre declare a resposta de sucesso — e o `404`, se o endpoint devolve `NotFound`.
- `WithSummary` é obrigatório e diz o que a rota faz. `WithDescription` é
  opcional; se usar, escreva algo — descrição vazia rende um bloco em branco no Scalar.
- Toda classe de endpoint precisa de **nome único na solução**: o `operationId` sai do
  nome da classe, e dois iguais geram um documento OpenAPI inválido.
- Nunca devolva mensagem de exceção ao cliente: o `GlobalErrorHandlingMiddleware` cuida disso.

Regras gerais: `AGENTS.md`.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall