Jamdesk Documentation logo

Exemplo de OpenAPI

Veja uma página de endpoint gerada pelo OpenAPI ao vivo e saiba como a Jamdesk renderiza requisições, respostas e autenticação diretamente da sua especificação.

POSThttps://jamdesk-docs.jamdesk.app/api/playground/demo/tickets

Create a new ticket for a customer issue or request.

Loading code example
Loading code example

Body

customer_idstringrequired

Customer identifier in Acme.

subjectstringrequired

Short summary of the issue.

priority"low" | "normal" | "high" | "urgent"
Allowed values: "low" | "normal" | "high" | "urgent"
tagsarray<string>
messagestringrequired

Detailed problem description.

Response

application/json

Ticket created

idstring
customer_idstring
subjectstring
prioritystring
status"open" | "pending" | "resolved"
Allowed values: "open" | "pending" | "resolved"
tagsarray<string>
messagestring
created_atstring<date-time>
updated_atstring<date-time>

Esta página é um endpoint ao vivo gerado a partir de uma especificação OpenAPI. A Jamdesk gera o schema da requisição, os modelos de resposta e os exemplos de código no painel da direita a partir da especificação.

Este exemplo usa a API de Suporte da Acme. Aponte api.openapi em docs.json para o seu arquivo de especificação para gerar seus endpoints.

Documentação em vários idiomas? Forneça um arquivo <spec>.<lang>.<ext> ao lado da sua especificação de origem (por exemplo, example-api.fr.yaml). A Jamdesk renderiza a versão traduzida nas páginas em /fr/.... Veja Traduzindo 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, a Jamdesk gera:

  • Um selo de endpoint mostrando o método e o caminho, com codificação de cores
  • Documentação de parâmetros para 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ável via api.examples.languages)
  • Detalhes de autenticação extraídos dos esquemas de segurança da especificação

A Jamdesk resolve todos os $ref da sua especificação. Organize os schemas com components/schemas como de costume.

A Jamdesk renderiza as descrições da sua especificação como Markdown, não como texto puro. As descrições de operações, parâmetros, corpo da requisição, respostas e schemas aceitam o mesmo negrito, código, 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 em docs.json em api.openapi. Depois, adicione openapi: /openapi/your-spec.yaml METHOD /path ao frontmatter de qualquer página. Veja o guia de configuração do OpenAPI para todos os detalhes.

Gere uma página para cada operação

Aponte uma aba de navegação para a especificação para que a Jamdesk crie toda a referência, em vez de escrever uma página por endpoint:

docs.json
{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Cada operação recebe uma página. A barra lateral é agrupada por tag. Arquivos .mdx versionados têm prioridade em caso de colisão de slug. Você pode adotar isso uma página por vez. Renomear um caminho na sua especificação redireciona a URL antiga em vez de quebrá-la. Veja navigation openapi para as regras completas e os limites atuais.

Escrevendo sua especificação em YAML? Passe-a pelo Validador de YAML gratuito para detectar erros de indentação e sintaxe antes que o build a analise.

Páginas relacionadas

Playground de API

Ative o teste interativo de API nas suas páginas de endpoint

Exemplos de Requisição/Resposta

Exemplo de endpoint escrito manualmente usando componentes MDX

Configuração do OpenAPI

Onde armazenar e referenciar arquivos OpenAPI

Referência do docs.json

Referência completa de configuração, incluindo api.openapi