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.

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:

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:

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çãoO 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çãoMétodo
Criar recursoMapPost("/admin/tracks")
Atualizar recurso completoMapPut("/admin/tracks/{id:guid}")
Atualizar parcialmenteMapPatch("/admin/tracks/{id:guid}")
Remover recursoMapDelete("/admin/tracks/{id:guid}")
Obter por IDMapGet("/admin/tracks/{id:guid}")
Listar / paginarMapGet("/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:

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:

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: 471kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall