Exemplo de OpenAPI
Veja um endpoint gerado pelo OpenAPI e saiba 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 ao vivo gerado a partir de uma especificação OpenAPI. O esquema 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 criação manual.
Este exemplo usa a API de suporte da Acme. Atualize api.openapi no seu docs.json para apontar para seu próprio arquivo de especificação e gerar endpoints reais.
Documentação em vários idiomas? Forneça um arquivo <spec>.<lang>.<ext> ao lado da especificação de origem (por exemplo, example-api.fr.yaml) e o Jamdesk renderizará 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 da API habilitado. 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 selo de endpoint que mostra o método e o caminho com codificação por cores
- Documentação de parâmetros de caminho, consulta, cabeçalho e corpo
- Esquemas de requisição e resposta, incluindo objetos aninhados e arrays
- 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 obtidos dos esquemas de segurança da especificação
Todas as referências $ref na especificação são resolvidas automaticamente, para que você possa organizar os esquemas com components/schemas normalmente.
Configurar OpenAPI
Coloque sua especificação OpenAPI 3.x (YAML ou JSON) no diretório openapi/, registre-a em 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.
Escrevendo sua especificação em YAML? Execute-a no Validador de YAML gratuito para detectar erros de indentação e sintaxe antes que o build a processe.