Beginnen met API-documentatie

De API in Document360 biedt een complete oplossing voor het creëren en beheren van API-referenties. Met deze functie kun je hoogwaardige API-documentatie genereren die gebruikers helpt je API's effectief te begrijpen en ermee om te gaan. Je kunt deze documentatie genereren door het API-specificatiebestand te uploaden vanaf een URL, een JSON/YAML/YML-bestand , of door te integreren met een CI/CD-flow. Document360 ondersteunt OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 en Postman-collecties.

Daarnaast stelt de Try it!- functie in Document360 je in staat om API-endpoints direct op de Knowledge base site te testen. De interactieve console op de Knowledge Base-site stelt ontwikkelaars in staat de benodigde parameters in te voeren en API-aanroepen uit te voeren, waardoor realtime antwoorden worden ontvangen. Deze functie is handig bij het oplossen van problemen en het begrijpen van hoe een API zich gedraagt zonder de documentatie te verlaten of code te schrijven.

OPMERKING

De sectie Try It! ondersteunt meerdere beveiligingsschema's tegelijkertijd, waardoor gebruikers eindpunten die gecombineerde authenticatiemethoden vereisen effectiever kunnen testen.

Webhooks (gebeurtenissen) in OpenAPI 3.1

Document360 ondersteunt webhooks die zijn gedefinieerd in OpenAPI 3.1. Webhooks verschijnen met een gebeurtenispictogram in je API-referentie en bevatten een payload-sectie gebaseerd op je schema. Als er geen voorbeeld wordt gegeven, toont Document360 een standaardvoorbeeld en een voorbeeldpayload. Try It is niet beschikbaar voor webhooks. Webhooks worden ondersteund voor bestandsuploads, URL-importen en CI/CD-flows.

API-documentatie onboarding

Bij het aanmelden voor Document360 kiezen gebruikers hun primaire gebruikssituatie in Stap 1 van de onboardingflow. Voor gebruikers die API-documentatie willen maken, biedt Document360 een gestroomlijnde onboarding-ervaring. Als je API-documentatie als je use case kiest, word je doorgestuurd naar de API-setupflow, waar je API-referenties kunt maken met de beschikbare opties.

In stap 2 van de onboardingflow heb je drie opties om een API-referentie te maken:

• API-bestand uploaden: Ondersteunt JSON/YAML/YML-bestanden (OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 en Postman-collecties).

• Aanmaken vanaf URL: Haalt automatisch de API-specificatie op van de gehoste URL.

• Probeer het voorbeeld van een API voor een huisdierenwinkel: Als je geen API-bestand klaar hebt, kun je het voorbeeldbestand (Pet store API) van Document360 gebruiken om je werkruimte te vullen.

Uploaden van een API-definitiebestand

Om een API-referentie te maken uit een API-definitiebestand, selecteer je de knop Upload API-bestand. Klik vervolgens op Uploaden vanaf mijn apparaat of sleep en drop-drop je API-specificatiebestand van je apparaat.

OPMERKING

De bestandsformaten die worden ondersteund voor het API-definitiebestand zijn JSON, YAML of YML.

Het systeem zal het bestand parsen en de API-referentie automatisch genereren.

• Als er eeny waarschuwingen/waarschuwingen worden gedetecteerd in het geüploade bestand, wordt tijdens de onboarding een overzicht op hoog niveau weergegeven. Je kunt diepgaande details bekijken in het kennisbankportaal in de logsectie onder Meer-opties binnen API-referenties.

• Als er een fout wordt gedetecteerd in het geüploade bestand (bijvoorbeeld Niet ondersteund bestandsformaat), vervang het geüploade bestand door een alternatief bestand.

Invoer van een API-documentatie-URL

Om een API-referentie te maken vanuit een API-documentatie-URL, selecteer je de knop 'Create from URL '. Voer vervolgens de URL van je OpenAPI-bestand in in het veld voor de URL van je API-definitie. Document360 zal de API-structuur ophalen en verwerken. Vergelijkbaar met bestandsuploads,

• Als er meldingen/waarschuwingen worden gedetecteerd, kun je deze bekijken in het kennisbankportaal in de logboeksectie onder Meer opties binnen API-referenties. Je kunt diepgaande details bekijken in het kennisbankportaal in de logsectie onder Meer-opties binnen API-referenties.

• Als er een fout wordt gedetecteerd (bijvoorbeeld Ongeldige URL), voer dan de geldige URL van je OpenAPI-bestand in.

API-installatie overslaan

Als je kiest voor de optie Try sample pet store API ,

• Document360 maakt automatisch een voorbeeld van een API-referentie aan (Pet store API).

• Dit zal beschikbaar zijn in draftmodus. Je kunt de eindpunten bekijken voordat je publiceert of je specificatiebestand uploaden en later publiceren.

Personaliseer je kennisbasis

In stap 3 kun je de URL van je gewenste website invoeren. Als je deze stap wilt overslaan, wordt het domein standaard het domein dat aan je registratie-e-mail is gekoppeld.

Merkrichtlijnen

In stap 4 worden je projectnaam, standaardtaal, brandinglogo en merkkleuren automatisch ingesteld op basis van de opgegeven URL. Je kunt deze velden echter aanpassen indien nodig. De taalinstellingen van je browser bepalen de standaardtaal. Engels wordt standaard geselecteerd als andere talen de taal van je browser niet ondersteunen.

OPMERKING

• Als je Spaans of Braziliaans Portugees als standaardtaal kiest, wordt de portaaltaal ingesteld op Spaans of Braziliaans Portugees. Anders wordt Engels de standaardtaal.

• Het brandinglogo en de primaire en secundaire kleuren worden van je website gehaald. Als je ervoor kiest deze stap over te slaan , wordt de projectnaam afgeleid van je registratie-e-mail, en worden het standaardlogo en de kleuren van Document360 toegepast.

Stel privacy van documentatie in

In stap 5 kunt u de gewenste privacy-instellingen voor uw site kiezen:

• Privé: Beperk de toegang tot de kennisbank zodat alleen teamaccounts de inhoud kunnen bekijken en ermee kunnen interageren, zodat deze veilig en intern blijft.

• Openbaar: Maak de kennisbank toegankelijk voor iedereen, inclusief externe gebruikers, zodat alle inhoud open toegankelijk is.

• Gemengd: Combineer privé- en publieke toegang door sommige delen van de kennisbasis zichtbaar te maken voor het publiek, terwijl andere secties beperkt blijven tot teamaccounts.

Klik tenslotte op Volgend om je API-onboardingflow te voltooien.

Je wordt doorgestuurd naar de API-documentatieruimte, waar:

• Je ziet de API-referentie van de API-specificatie die je tijdens de onboarding hebt opgegeven.

• Als je geen API-specificatie hebt gegeven, is er een voorbeeld van een API-referentie (Pet Shop API) beschikbaar in conceptmodus.  

Autorisatietechnieken

Bij het interacteren met een API is het belangrijk ervoor te zorgen dat alleen geautoriseerde gebruikers toegang hebben tot bepaalde gegevens of specifieke acties kunnen uitvoeren. Dit gebeurt met autorisatietechnieken, die de toegang en rechten controleren. Document360 ondersteunt verschillende autorisatiemethoden om uw API te beveiligen, waaronder:

• Basisauthenticatie: Vereist een gebruikersnaam en wachtwoord die in het verzoek worden doorgegeven.

• Bearer token: Authenticeert met een token dat na het inloggen wordt gegenereerd.

• API-sleutel: Gebruikt een unieke sleutel, doorgegeven in de requestheaders, voor authenticatie.

• OAuth2: Beveiligt API's via verschillende stromen, zoals autorisatiecode, PKCE, clientgegevens en impliciete stromen.

• OpenID Connect: Breidt OAuth2 uit door gebruikersidentiteitsverificatie toe te voegen.

Autorisatieoverwegingen (OAuth2 en OpenID)

Bij het werken met API's die OAuth2 of OpenID gebruiken voor autorisatie, zijn bepaalde instellingen essentieel voor een goede functionaliteit.

• Redirect URI: Dit is de URL waar de gebruiker naartoe wordt doorgestuurd na het voltooien van een autorisatieflow. Zorg ervoor dat je de URI instelt in het formaat: domain/oauth. Bijvoorbeeld: https://apidocs.document360.com/oauth.

• Stille verlenging: Stille verlenging ververst automatisch het autorisatietoken op de achtergrond, zodat gebruikers zich niet tijdens hun sessie hoeven te authenticeren. Dit houdt hun sessie actief zonder onderbreking. Om te voorkomen dat autorisatie verloopt tijdens sessies waarin gebruikers interactie hebben met de Try It!- functie, vernieuwt Document360 automatisch het ververstoken op de achtergrond. Dit zorgt ervoor dat gebruikers zich niet handmatig hoeven te herauthenticeren.

Aankoop

Je hebt toegang tot 1 API-werkruimte als onderdeel van alle betaalde Document360-abonnementen (Professional, Business en Enterprise). Als je extra API-werkruimtes wilt kopen,

1. Ga naar () > Kennisbankportaal > Facturering > Mijn plan.

2. Klik op Add-on kopen.

3. Voeg het gewenste aantal API-documentatiewerkruimtes toe. Bekijk de kosten van de toevoeging en het verschuldigde bedrag.

4. Klik op Bevestig betaling om door te gaan met de betaling.

Probleemoplossing

API-toegangsproblemen

Fout: 400 fout – API-toegang is uitgeschakeld. Neem contact op met uw projectbeheerder.

Deze fout doet zich voor wanneer de publieke API-toegang wordt gedeactiveerd in de projectinstellingen.

Stappen om op te lossen:

1. Navigeer naar () > AI-instellingen > Eddy AI-instellingen in het kennisbasisportaal.

2. Zorg er onder het AI-zoekpakketgedeelte voor dat het selectievakje Public API is aangevinkt.

   

3. Als het probleem zich blijft voordoen na het volgen van deze stappen, neem dan contact op met het Document360-ondersteuningsteam voor verdere hulp: Neem contact op met Document360 Support

API-importproblemen

Fout: Ongeldig formaat – API-bestandsupload mislukte.

Deze fout doet zich voor wanneer één of meer antwoorden in het OpenAPI-specificatiebestand de vereiste content sectie missen.

Hoewel het bestand validatie kan doorstaan in Swagger Editor, handhaaft Document360 strikte OpenAPI-validatieregels en vereist dat alle antwoorden expliciet het mediatype (bijvoorbeeld application/json) en de schemareferentie definiëren.

Stappen om op te lossen:

1. Open je OpenAPI (Swagger) specificatiebestand in een teksteditor of IDE.

2. Zoek alle responsdefinities die leeg zijn of verwijs direct naar een schema zonder content blok.

   Voorbeeld van een onjuiste reactie:

   responses:
     "200": {}

3. Werk de responsdefinitie bij om een inhoudssectie met het juiste mediatype en schemareferentie op te nemen.

   Voorbeeld van een correct antwoord:

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/UserGroupFetchResponse"

4. Sla het bestand op en probeer het opnieuw te uploaden naar Document360.

Samenvatting en tags die niet worden weergegeven na het importeren van een API-specificatie

Fout: De geïmporteerde eindpunten tonen niet de juiste titels en verschijnen niet onder de verwachte tagmappen.

Dit probleem doet zich voor wanneer de summary en-velden tags in de OpenAPI-specificatie op padniveau worden gedefinieerd in plaats van onder het operatie-object (get, post, put, of delete).

Daarnaast moet het tags veld altijd als een array worden geschreven, zelfs als slechts één tag wordt gebruikt.

Stappen om op te lossen:

1. Open je OpenAPI-specificatiebestand in een teksteditor.

2. Verplaats de samenvatting- en tagvelden binnen elk operatieobject.

3. Zorg ervoor dat de waarde van de tags als een array wordt geschreven.

   Onjuist voorbeeld:

   /dms/modules/{module-name}/types/logical/{logical-type}:
     summary: Type & Logical type
     tags: Logical Types
     get:
       ...
   

   Correct voorbeeld:

   /dms/modules/{module-name}/types/logical/{logical-type}:
     get:
       summary: Type & Logical type
       tags: ["Logical Types"]
       ...
   

4. Na het uitvoeren van deze updates sla je het bestand op en importeer je het opnieuw in Document360.

   De geïmporteerde artikelen gebruiken nu de summary waarde als artikeltitel, en tag-gebaseerde mappen worden correct aangemaakt.

Gerelateerde video's

Ervaar onze moderne API-documentatie in Document360 als nooit tevoren

Test API-endpoints direct vanuit Documentatie met de Probeer het-functie

Aanvullende informatie

Introductie van API-documentatie: Verbeter je API-ervaring - Klik om te lezen