Endpoints testen met Try it!

Try It! is de interactieve API-console van Document360, direct ingebed in je gepubliceerde API-referentie. Het stelt ontwikkelaars in staat echte verzoeken naar je API-eindpunten te sturen en live antwoorden te zien zonder de documentatie te verlaten of code te schrijven.

Dit artikel legt uit hoe Try It! werkt, wat ontwikkelaars nodig hebben om het te gebruiken, en hoe je elke ondersteunde authenticatiemethode in je API-specificatie kunt configureren.

Wat Try It! doet

Vanaf elke endpointpagina in je gepubliceerde API-referentie kunnen ontwikkelaars:

• Selecteer een HTTP-methode en eindpunt
• Vul de vereiste en optionele parameters in
• Configureer authenticatiegegevens
• Stuur een live verzoek en bekijk de reactie in realtime
  

Vereisten voor Try It! om te verschijnen

Try It! verschijnt alleen op een endpointpagina wanneer beide van de volgende correct zijn gedefinieerd in je API-specificatiebestand:

• Een server-URL - het servers gedeelte van je specificatie moet minstens één geldige basis-URL bevatten.
• Een servervariabele - de variabele moet naast de URL worden gedefinieerd.

Als een van deze ontbreekt, zal de Try It!-knop niet zichtbaar zijn op de Knowledge Base-site.

Correct server-URL-formaat

servers:
  - url: https://api.yourdomain.com
    description: Production

Voor API's met meerdere regio's, definieer meerdere items:

servers:
  - url: https://api.yourdomain.com
    description: Global

  - url: https://api.us.yourdomain.com
    description: US region

Hoe verzoeken worden gerouteerd

Wanneer een ontwikkelaar op Try it & see response klikt, zal de verzoek-URL voorafgaan tryit.document360.io aan de basis-URL van je API. Bijvoorbeeld:

https://tryit.document360.io/https://api.yourdomain.com/v2/your-endpoint

Dit is verwacht gedrag. Het tryit.document360.io subdomein wordt intern gebruikt om API-testverzoeken te routeren en te verwerken. Het beïnvloedt de functionaliteit niet, maar verzoeken geven nog steeds de juiste resultaten van je API terug.

Ondersteunde authenticatiemethoden

Document360 leest de authenticatieconfiguratie direct uit je OpenAPI-specificatie en toont deze op twee plaatsen: de endpoint-documentatie en de Try It!-console.

Authenticatiemethoden worden gedefinieerd in je OpenAPI-specificatie onder components/securitySchemes en toegepast op individuele eindpunten met behulp van het security veld.

Basisauthenticatie

Basisauthenticatie vereist een gebruikersnaam en wachtwoord die worden gecodeerd en doorgegeven in de Authorization header van elk verzoek.

In je OpenAPI-specificatie:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

Pas het toe op een eindpunt:

/your-endpoint:
  get:
    security:
      - basicAuth: []

In Try It! worden ontwikkelaars gevraagd een gebruikersnaam en wachtwoord in te voeren voordat ze een verzoek versturen.

Dragertoken

Bearer-tokenauthenticatie gebruikt een token dat in de Authorization header wordt doorgegeven als Bearer <token>.

In je OpenAPI-specificatie:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

Pas het toe op een eindpunt:

/your-endpoint:
  get:
    security:
      - BearerAuth: []

API-sleutel

API-sleutelauthenticatie gebruikt een unieke sleutel die in de requestheaders wordt doorgegeven.

In je OpenAPI-specificatie:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Pas het toe op een eindpunt:

/your-endpoint:
  get:
    security:
      - ApiKeyAuth: []

In Try It! worden ontwikkelaars gevraagd hun API-sleutelwaarde in te voeren. Het wordt verzonden in de headernaam die in je specificatie is gedefinieerd (X-API-Key in het bovenstaande voorbeeld).

OAuth2

OAuth2 wordt ondersteund met vier stromen. Gebruik de flow die overeenkomt met hoe jouw API toegangstokens uitgeeft.

Vereiste configuratie voor Try It!

Wanneer je API OAuth2 gebruikt, moeten er twee extra instellingen worden geconfigureerd:

Redirect URI — Nadat een ontwikkelaar de OAuth-autorisatieflow heeft voltooid, wordt hij of zij teruggestuurd naar Document360. Voeg de redirect-URI van Document360 toe aan de lijst van toegestane redirect-URI's van je OAuth-provider:

https://your-apidocs-domain.com/oauth

Vervang your-apidocs-domain.com het door het domein waarop je document360 API-documentatie wordt gepubliceerd.

Stille verlenging — Document360 verst automatisch het OAuth-toegangstoken op de achtergrond terwijl een ontwikkelaar actief met Try It! bezig is. Dit voorkomt dat de sessie halverwege gebruik verloopt. Er is geen configuratie nodig aan jouw kant, want dit wordt automatisch afgehandeld door Document360.

Voorbeeld specificatiedefinitie (Autorisatiecodeflow)

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

OpenID Connect breidt OAuth2 uit door gebruikersidentiteitsverificatie toe te voegen. Het is geconfigureerd vergelijkbaar met OAuth2 en heeft dezelfde redirect-URI- en stille verlengingsvereisten.

In je OpenAPI-specificatie:

components:
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration

Dezelfde redirect-URI-vereiste geldt:

https://your-apidocs-domain.com/oauth

Meerdere beveiligingsschema's toepassen op één eindpunt

Als een eindpunt meer dan één authenticatiemethode tegelijk vereist, definieer deze dan samen onder op security het operationele niveau:

/secure-endpoint:
  get:
    security:
      - BearerAuth: []
        ApiKeyAuth: []

Dit vereist zowel een Bearer-token als een API-sleutel voordat het verzoek kan worden verzonden. Try It! ondersteunt meerdere beveiligingsschema's in één sessie.

What Try It! ondersteunt geen ondersteuning

• Webhooks - Try It! is niet beschikbaar voor webhook-definities. Webhook-pagina's tonen het payloadschema en een voorbeeld, maar kunnen geen testverzoeken versturen.
• Instance-based dynamische antwoorden - Document360 volgt de OpenAPI-specificatie, die een consistente statische structuur definieert voor verzoek- en responsobjecten. Als je API verschillende antwoorden geeft voor hetzelfde eindpunt in verschillende omgevingen of instanties, zal Try It! alleen weerspiegelen wat in de specificatie is gedefinieerd.

FAQ