Skip to main content

​
Convenções da documentação

​
Descrição de endpoint (OpenAPI)

A description de um endpoint é uma frase curta dizendo o que ele faz, como “Define as tags do pedido.” ou “Lista as tags da loja.”. Ela aparece logo abaixo do título da página, e um parágrafo ali empurra o playground pra baixo e não é lido. O resto vai em um componente depois dessa frase:
  • <Note>: como usar a rota (semântica de substituição, de onde vêm os IDs, qual parâmetro escolher);
  • <Warning>: o que pode dar errado ou ter efeito irreversível.
Use o bloco >- com uma linha em branco entre a frase e o componente. Sem a linha em branco, o Mintlify junta os dois no mesmo parágrafo. Exemplos em openapi/customers.yaml e openapi/orders.yaml. Regras do texto:
  • não repetir na descrição o que já está no schema (limites de campo, tipos);
  • escopo de API fica na tabela de api-reference/oauth.mdx, não na descrição;
  • nunca usar travessão (—) em texto da CentralCart.