biellts/universidade-automatiza / .claude/skills/backend-criar-endpoint-minimal-api
backend-criar-endpoint-minimal-api
VerifiedCria 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çã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:
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
IUseCaseEndpointcompublic 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 retornaResults.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âmetroGuid id. - Enums trafegam pelo nome no JSON (
"Cliente"), viaJsonStringEnumConverterjá configurado no host. - Sempre declare a resposta de sucesso — e o
404, se o endpoint devolveNotFound. 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
operationIdsai do nome da classe, e dois iguais geram um documento OpenAPI inválido. - Nunca devolva mensagem de exceção ao cliente: o
GlobalErrorHandlingMiddlewarecuida disso.
Regras gerais: AGENTS.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |