Exemplo de Documentação Back-end

Conteúdo de exemplo: substitua endpoints, arquivos, payloads e regras pelos dados reais da funcionalidade documentada.

Visão geral

Este documento demonstra a estrutura recomendada para documentar uma funcionalidade de Back-end. O exemplo apresenta um serviço fictício de criação de recursos, incluindo contrato da API, validações, regras de negócio, arquivos envolvidos e cenários de teste.

Objetivo

Disponibilizar um endpoint autenticado para cadastrar um novo recurso, validar os dados recebidos, impedir duplicidades e retornar um contrato consistente para os consumidores da API.

Arquitetura do fluxo

Endpoint

Criar recurso

POST /api/v1/resources
Authorization: Bearer <token>
Content-Type: application/json

Corpo da requisição

{
  "name": "Recurso de exemplo",
  "description": "Descrição opcional do recurso",
  "active": true
}

Campo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome único do recurso
`description`	`string`	Não	Informações complementares
`active`	`boolean`	Não	Estado inicial; padrão `true`

Resposta de sucesso

Status: 201 Created

{
  "id": "0194f0c8-4c9d-7c2e-a5df-7ad45af324b1",
  "name": "Recurso de exemplo",
  "description": "Descrição opcional do recurso",
  "active": true,
  "createdAt": "2026-08-19T14:00:00.000Z"
}

Regras de negócio

Código	Regra
RN01	O nome é obrigatório e deve possuir entre 3 e 120 caracteres
RN02	Não pode existir outro recurso ativo com o mesmo nome
RN03	O campo `active` assume `true` quando não for informado
RN04	A criação exige um usuário autenticado com a permissão adequada
RN05	Espaços no início e no final do nome devem ser removidos

Validações e erros

Status	Código	Quando ocorre
`400`	`VALIDATION_ERROR`	Payload ausente ou campo inválido
`401`	`UNAUTHORIZED`	Token ausente, inválido ou expirado
`403`	`FORBIDDEN`	Usuário sem permissão para criar o recurso
`409`	`RESOURCE_ALREADY_EXISTS`	Já existe um recurso com o mesmo nome
`500`	`INTERNAL_SERVER_ERROR`	Falha inesperada durante o processamento

Exemplo de erro padronizado:

{
  "statusCode": 409,
  "code": "RESOURCE_ALREADY_EXISTS",
  "message": "Já existe um recurso com este nome",
  "timestamp": "2026-08-19T14:00:00.000Z"
}

Arquivos envolvidos

Arquivo	Responsabilidade
`src/modules/resources/resource.controller.ts`	Recebe a requisição e define o contrato HTTP
`src/modules/resources/resource.service.ts`	Executa as regras de negócio
`src/modules/resources/resource.repository.ts`	Acessa e persiste os dados
`src/modules/resources/dto/create-resource.dto.ts`	Define e valida o payload de entrada
`src/modules/resources/entities/resource.entity.ts`	Representa a entidade persistida
`src/modules/resources/errors/resource.errors.ts`	Centraliza os erros do domínio

Implementação principal

async function createResource(input: CreateResourceInput) {
  const name = input.name.trim();
  const existingResource = await repository.findActiveByName(name);

  if (existingResource) {
    throw new ResourceAlreadyExistsError(name);
  }

  return repository.create({
    ...input,
    name,
    active: input.active ?? true,
  });
}

Persistência

Tabela de exemplo: resources.

Coluna	Tipo	Observação
`id`	`uuid`	Chave primária
`name`	`varchar(120)`	Nome pesquisável do recurso
`description`	`text`	Conteúdo opcional
`active`	`boolean`	Exclusão lógica ou disponibilidade
`created_at`	`timestamp`	Data de criação
`updated_at`	`timestamp`	Data da última alteração

Segurança

O endpoint deve exigir autenticação.
A autorização deve ser validada antes da regra de negócio.
Tokens, senhas e dados sensíveis não devem aparecer nos logs.
Entradas devem ser validadas antes de chegar ao repositório.
Consultas devem usar parâmetros para evitar injeção.

Observabilidade

Registre informações suficientes para investigar falhas sem expor dados sensíveis:

identificador da requisição;
identificador do usuário ou serviço solicitante;
duração da operação;
resultado da operação;
código de erro do domínio;
stack trace somente nos logs internos apropriados.

Como validar

Inicie a API e suas dependências.
Obtenha um token de um usuário autorizado.
Envie uma requisição válida e confirme o status 201.
Consulte o banco e confirme a persistência do recurso.
Repita a requisição com o mesmo nome e confirme o status 409.
Remova o token e confirme o status 401.
Use um usuário sem permissão e confirme o status 403.
Envie campos inválidos e confirme o status 400.

Cenários de teste

Cenário	Resultado esperado
Payload válido	Recurso criado e retornado com status `201`
Nome com espaços externos	Nome normalizado antes de salvar
Nome duplicado	Erro `RESOURCE_ALREADY_EXISTS`
Campo obrigatório ausente	Erro `VALIDATION_ERROR`
Token ausente	Erro `UNAUTHORIZED`
Usuário sem permissão	Erro `FORBIDDEN`
Falha no banco	Erro interno tratado e registrado

Visão geral​

Objetivo​

Arquitetura do fluxo​

Endpoint​

Criar recurso​

Corpo da requisição​

Resposta de sucesso​

Regras de negócio​

Validações e erros​

Arquivos envolvidos​

Implementação principal​

Persistência​

Segurança​

Observabilidade​

Como validar​

Cenários de teste​

Checklist para adaptar este exemplo​