Try It! é o console interativo da API do Document360, incorporado diretamente na sua referência de API publicada. Ele permite que desenvolvedores enviem requisições reais para seus endpoints da API e vejam respostas ao vivo sem sair da documentação ou escrever código.
Este artigo explica como o Try It! funciona, o que os desenvolvedores precisam para usá-lo e como configurar cada método de autenticação suportado na sua especificação de API.
O que tentar!
A partir de qualquer página de endpoint na sua referência de API publicada, os desenvolvedores podem:
- Selecione um método HTTP e um ponto final
- Preenchimento dos parâmetros necessários e opcionais
- Configurar credenciais de autenticação
- Envie uma solicitação ao vivo e visualize a resposta em tempo real
Try It! não está disponível para webhooks. As páginas do Webhook mostram o esquema da carga útil e um exemplo, mas não podem enviar requisições de teste.
Requisitos para que o Try It! apareça
Try It! só aparece em uma página de endpoint quando ambos os seguintes estão corretamente definidos no seu arquivo de especificação da API:
- Uma URL de servidor – a
serversseção da sua especificação deve conter pelo menos uma URL base válida. - Uma variável servidor – a variável deve ser definida junto com a URL.
Se algum desses estiver faltando, o botão Experimente! não será visível no site da base de conhecimento.
Formato correto da URL do servidor
servers:
- url: https://api.yourdomain.com
description: Production
Para APIs com múltiplas regiões, defina múltiplas entradas:
servers:
- url: https://api.yourdomain.com
description: Global
- url: https://api.us.yourdomain.com
description: US region
As URLs acima são exemplos. Use a URL base real da sua API.
Como as requisições são roteadas
Quando um desenvolvedor clica em Tente & veja resposta, a URL da solicitação será tryit.document360.io incluída como prependida à URL base da sua API. Por exemplo:
https://tryit.document360.io/https://api.yourdomain.com/v2/your-endpoint
Esse é um comportamento esperado. O tryit.document360.io subdomínio é usado internamente para rotear e processar solicitações de teste da API. Isso não afeta a funcionalidade, mas as requisições ainda retornam os resultados corretos da sua API.
Métodos de autenticação suportados
O Document360 lê a configuração de autenticação diretamente da sua especificação OpenAPI e a apresenta em dois lugares: a documentação do endpoint e o console Try It!.
| Método | Como funciona |
|---|---|
| Autenticação básica | Nome de usuário e senha passados no cabeçalho da solicitação. |
| Token de portador | Um token gerado após o login, passado pelo cabeçalho de Autorização. |
| Chave API | Uma chave única era passada nos cabeçalhos de requisição. |
| OAuth2 | Suporta Código de Autorização, PKCE, Credenciais do Cliente e fluxos implícitos. |
| OpenID Connect | Estende o OAuth2 para adicionar verificação de identidade de usuário. |
Os métodos de autenticação são definidos na sua especificação OpenAPI sob components/securitySchemes e aplicados a endpoints individuais usando o security campo.
Try It! suporta múltiplos esquemas de segurança simultaneamente. Isso significa que os desenvolvedores podem testar endpoints que exigem métodos de autenticação combinados dentro da mesma sessão.
Autenticação básica
A autenticação básica requer um nome de usuário e senha codificados e passados no Authorization cabeçalho de cada solicitação.
Na sua especificação OpenAPI:
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
Aplique isso a um endpoint:
/your-endpoint:
get:
security:
- basicAuth: []
No Try It!, os desenvolvedores serão solicitados a inserir um nome de usuário e senha antes de enviar uma solicitação.
Token de portador
A autenticação do token portador usa um token passado no Authorization cabeçalho como Bearer <token>.
Na sua especificação OpenAPI:
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
O Document360 exige que o esquema de segurança seja nomeado BearerAuth (sensível a maiúsculas e minúsculas). Se essa definição estiver ausente na sua especificação, clicar em Experimentar! em um endpoint afetado retornará um erro 403. Durante a importação, o Document360 sinalizará isso na seção de Alertas se detectar uma definição de BearerAuth faltante.
Aplique isso a um endpoint:
/your-endpoint:
get:
security:
- BearerAuth: []
Chave API
A autenticação por chave API utiliza uma chave única passada nos cabeçalhos das requisições.
Na sua especificação OpenAPI:
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
Aplique isso a um endpoint:
/your-endpoint:
get:
security:
- ApiKeyAuth: []
No Try It!, os desenvolvedores serão solicitados a inserir o valor da chave da API. Ele será enviado no nome do cabeçalho definido na sua especificação (X-API-Key no exemplo acima).
OAuth2
O OAuth2 é suportado por quatro fluxos. Use o fluxo que corresponda à forma como sua API emite os tokens de acesso.
| Fluxo | Quando usá-lo |
|---|---|
| Código de Autorização | Aplicações do lado do servidor onde o segredo do cliente pode ser mantido confidencial. |
| PKCE | Clientes públicos, como aplicativos de página única e aplicativos móveis, onde o segredo não pode ser mantido confidencial. |
| Credenciais do Cliente | Comunicação máquina a máquina onde nenhum usuário está envolvido. |
| Implícito | Fluxo legado. Não recomendado para novas implementações. |
Configuração necessária para o Try It!
Quando sua API usa OAuth2, duas configurações adicionais precisam ser configuradas:
URI de redirecionamento — Após um desenvolvedor concluir o fluxo de autorização OAuth, ele é redirecionado de volta para o Document360. Adicione o URI de redirecionamento do Document360 à lista de URIs permitidos de redirecionamento do seu provedor OAuth:
https://your-apidocs-domain.com/oauth
Substitua your-apidocs-domain.com pelo domínio onde a documentação da sua API do Document360 está publicada.
Renovação silenciosa — O Document360 atualiza automaticamente o token de acesso OAuth em segundo plano enquanto um desenvolvedor está usando ativamente o Try It!. Isso evita que a sessão expire no meio do uso. Nenhuma configuração é necessária do seu lado porque isso é gerenciado automaticamente pelo Document360.
Exemplo de definição de especificação (Fluxo de código de autorização)
components:
securitySchemes:
oauth2Auth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.yourdomain.com/oauth/authorize
tokenUrl: https://auth.yourdomain.com/oauth/token
scopes:
read: Read access
write: Write access
OpenID Connect
O OpenID Connect estende o OAuth2 adicionando verificação de identidade de usuário. Ele é configurado de forma semelhante ao OAuth2 e possui os mesmos requisitos de URI de redirecionamento e renovação silenciosa.
Na sua especificação OpenAPI:
components:
securitySchemes:
openIdConnect:
type: openIdConnect
openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration
O mesmo requisito de URI de redirecionamento se aplica:
https://your-apidocs-domain.com/oauth
Aplicando múltiplos esquemas de segurança a um único endpoint
Se um endpoint requer mais de um método de autenticação simultaneamente, defina-os juntos sob security o nível operacional:
/secure-endpoint:
get:
security:
- BearerAuth: []
ApiKeyAuth: []
Isso exige que tanto um token Portador quanto uma chave API sejam fornecidos antes que a solicitação possa ser enviada. O Try It! suporta múltiplos esquemas de segurança em uma única sessão.
O que Tryit! não suporta
- Webhooks - Try It! não está disponível para definições de webhooks. As páginas do Webhook mostram o esquema da carga útil e um exemplo, mas não podem enviar requisições de teste.
- Respostas dinâmicas baseadas em instâncias - O Document360 segue a especificação OpenAPI, que define uma estrutura estática consistente para objetos de requisição e resposta. Se sua API retorna respostas diferentes para o mesmo endpoint em ambientes ou instâncias diferentes, o Try It! refletirá apenas o que está definido na especificação.
FAQ
Por que a URL do Try It! inclui tryit.document360.io?
Esse é um comportamento esperado. O tryit.document360.io subdomínio é usado internamente para rotear e processar solicitações de teste da API. Isso não afeta a funcionalidade – as requisições ainda retornam os resultados corretos da sua API.
Posso testar endpoints que exigem mais de um método de autenticação?
Sim. Try It! suporta múltiplos esquemas de segurança simultaneamente. Desenvolvedores podem configurar e enviar credenciais para múltiplos esquemas em uma única solicitação.
Um agente de IA pode alternar entre MCP e a API padrão dentro do mesmo fluxo de trabalho?
Sim. Um único fluxo de trabalho pode usar o MCP para as etapas de raciocínio e ação — busca, leitura, escrita e chamar diretamente a API padrão para operações fora do escopo do MCP. As duas interfaces não são mutuamente exclusivas; Eles acessam a mesma base de conhecimento subjacente.