OpenAPI

Os schemas e decorators já descrevem a API. O Empilha usa essas mesmas declarações para gerar OpenAPI 3.1.

Ative

const AppModule = defineModule({
  name: "app",
  controllers: [TaskController],
});
const app = await createApplication(AppModule, {
  configure: (app) => app.openapi({
    title: "Tasks API",
    version: "1.0.0",
  }),
});

Ou configure em empilha.config.ts, como no capítulo anterior.

Dois endpoints aparecem:

Endpoint	Conteúdo
GET /openapi.json	documento OpenAPI 3.1
GET /docs	Swagger UI

O documento vem do contrato

Declaração	OpenAPI
@Controller, @Get, @Post…	path e método
@Param, @Query, @Header	parâmetros
@QueryParams	parâmetros, tipos e defaults
@Body	request body
@Returns	schema de sucesso
@Status	status de sucesso
@Identity, @Roles, @Guard	segurança bearer
@NotFoundWhenEmpty	resposta 404

Schemas recursivos são registrados em components.schemas e usados pelas rotas com referências $ref, em vez de serem expandidos infinitamente inline.

O endpoint de criação já é documentável:

import { queryArtifacts } from "../queries/query-artifacts";

@Post("/")
@Body(CreateTask)
@Returns(Task)
@Roles("user")
@Sql(queryArtifacts.taskCreate)
@Result("one")
create() {}

Declare @Returns(Schema) sempre que possível. Sem esse decorator, a rota continua funcionando, mas o OpenAPI só consegue descrever a resposta como Successful response, sem um schema de conteúdo.

Exemplos definidos no schema TypeBox também aparecem no Swagger UI:

const Url = t.String({ examples: ["https://example.com"] });

Não existe um segundo arquivo descrevendo body e resposta.

Agrupe por tags

@Controller("/tasks", { tags: ["Tasks"] })
export class TaskController {}

Sem tags explícitas, o nome do controller é usado.

Erros

Todas as rotas incluem respostas padronizadas 400 e 500. Rotas protegidas incluem 401 e 403; @NotFoundWhenEmpty adiciona 404.

Swagger UI sem dependência externa

/openapi.json e todos os assets da interface /docs são servidos localmente. Depois que a aplicação estiver compilada, o Swagger UI não depende de CDN nem de acesso à internet no navegador.

O schema é a fonte

Se a documentação estiver errada, corrija o decorator ou schema da rota. Não mantenha uma descrição paralela.