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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.5 KB |
SKILL.md
View on GitHub---
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`.
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: 472k | 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: 323k | 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: 323k | 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: 323k | Updated | Claude CodeCodex | Verified | Install |