Exemplo de OpenAPI
Veja uma página de endpoint gerada por OpenAPI e aprenda como o Jamdesk renderiza requisições, respostas e autenticação diretamente da sua especificação.
Create a new ticket for a customer issue or request.
Body
customer_idstringrequiredCustomer identifier in Acme.
subjectstringrequiredShort summary of the issue.
priority"low" | "normal" | "high" | "urgent""low" | "normal" | "high" | "urgent"tagsarray<string>messagestringrequiredDetailed problem description.
Response
Ticket created
idstringcustomer_idstringsubjectstringprioritystringstatus"open" | "pending" | "resolved""open" | "pending" | "resolved"tagsarray<string>messagestringcreated_atstring<date-time>updated_atstring<date-time>Esta página demonstra um endpoint ativo gerado a partir de uma especificação OpenAPI. O schema da requisição, os modelos de resposta e os exemplos de código no painel direito são gerados automaticamente a partir da especificação, sem necessidade de autoria manual.
Este exemplo usa a API de suporte da Acme. Atualize api.openapi no seu docs.json para apontar para o seu próprio arquivo de especificação e gerar endpoints reais.
Documentação multilíngue? Forneça um arquivo <spec>.<lang>.<ext> ao lado da especificação de origem (por exemplo, example-api.fr.yaml) e o Jamdesk exibirá a versão traduzida quando os usuários visualizarem a página em /fr/.... Consulte Tradução de especificações OpenAPI.
Esta página tem o Playground de API ativado. Clique em Try it no endpoint acima para testar a API ao vivo.
O que é gerado
A partir de uma única linha openapi no frontmatter, o Jamdesk gera automaticamente:
- Um badge de endpoint mostrando o método e o caminho com codificação por cores
- Documentação de parâmetros de caminho, consulta, cabeçalho e corpo
- Schemas de requisição e resposta, incluindo objetos e arrays aninhados
- Exemplos de código em cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust e PHP (configuráveis por meio de
api.examples.languages) - Detalhes de autenticação extraídos dos esquemas de segurança da especificação
Todas as referências $ref na sua especificação são resolvidas automaticamente, para que você possa organizar os schemas com components/schemas normalmente.
As descrições na sua especificação são renderizadas como Markdown, não exibidas como texto bruto — as descrições de operações, parâmetros, corpos de requisição, respostas e schemas oferecem suporte ao mesmo negrito, code, listas, links e tabelas GFM que você escreveria em uma página .mdx.
Configurando o OpenAPI
Coloque sua especificação OpenAPI 3.x (YAML ou JSON) no diretório openapi/, registre-a no docs.json em api.openapi e adicione openapi: /openapi/your-spec.yaml METHOD /path ao frontmatter de qualquer página. Consulte o guia de configuração do OpenAPI para obter todos os detalhes.
Gerar uma página para cada operação
Em vez de criar uma página para cada endpoint, aponte uma aba de navegação para a especificação e deixe o Jamdesk criar toda a referência:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": { "source": "/openapi/api.yaml", "generate": true }
}
]
}
}Cada operação recebe uma página, e a barra lateral é agrupada por tag. Arquivos .mdx submetidos têm prioridade em caso de conflito de slug, para que você possa fazer a adoção gradualmente; além disso, renomear um caminho na especificação redireciona a URL antiga em vez de quebrá-la. Consulte navigation openapi para conhecer todas as regras e limitações atuais.
Escrevendo sua especificação em YAML? Execute-a pelo Validador de YAML gratuito para identificar erros de indentação e sintaxe antes que o build faça a análise.