API-documentatie beheren

De API-documentatiefunctie in Document360 maakt het eenvoudig om duidelijke, interactieve documentatie te maken door je API-specificatiebestanden te uploaden. Dit proces bouwt automatisch gedetailleerde documentatie op die alles behandelt, van API-eindpunten tot methoden en reacties, waardoor ontwikkelaars uw API effectiever kunnen begrijpen en gebruiken.  

API-documentatie genereren

Er zijn drie methoden om API-documentatie te genereren in Document360:

• Van een URL

• Uit een JSON/YAML/YML-bestand

• Met een CI/CD-stroom

OPMERKING

Document360 ondersteunt OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 en Postman API-specificaties.

API-documentatie genereren uit een API-specificatiebestand

Om API-referenties te genereren uit een API-specificatiebestand (JSON/YAML/YML),

1. Navigeer naar het gewenste project in het kennisbankportaal.

2. Selecteer API-documentatie ({ }) in de linker navigatiebalk.

3. Klik op het keuzemenu Aanmaken in de bovenste navigatiebalk en selecteer Nieuwe API. Dit toont het referentievenster voor de nieuwe API .

4. Selecteer de knop Upload API-definitie in het referentievenster Nieuwe API .

5. Klik op Uploaden vanaf mijn apparaat of Kies van Drive om het bestand van jouw apparaat te selecteren, of respectievelijk op Document360 Drive. Je kunt je bestand ook direct slepen en neerzetten in het referentievenster Nieuwe API.

OPMERKING

Het importproces van API-documentatie ondersteunt subcategorieën op tweede niveau met het > symbool in OpenAPI-tags (bijv. Pets > Details). Dit maakt een nettere, geneste organisatie van eindpunten mogelijk, behoudt de structuur tijdens de hersynchronisatie en zorgt voor een correcte weergave en navigatie in het linkerpaneel van de API-referentie.

Als je geüploade bestand bijbehorende waarschuwingen of waarschuwingen bevat, kun je deze bekijken door de dropdowns Alerts en Warnings uit te breiden, die verschijnen in het referentievenster Nieuwe API.

6. Klik op Nieuwe API-referentie om naar het bevestigingsvenster Publiceren te navigeren. Je ziet een succesbericht in het venster, samen met het aantal categorieën en artikelen dat is aangemaakt.

7. Klik op Publiceren om je API-documentatie te genereren.

OPMERKING

Om je documentatie te bekijken voordat je publiceert, klik je op Sluiten om terug te keren naar het Documentatiescherm. Je concept is zichtbaar in het Categorieën & Artikelen-venster .

API-documentatie genereren vanuit een URL

Om het API-specificatiebestand als URL naar Document360 te uploaden,

1. Navigeer naar het gewenste project in het kennisbankportaal.

2. Selecteer API-documentatie ({ }) in de linker navigatiebalk.

3. Klik op de keuzemenu Aanmaken in de bovenste navigatiebalk en selecteer Nieuwe API, of klik op de knop Nieuwe API rechtsboven. Dit toont het referentiepaneel van de nieuwe API .

4. Selecteer in het scherm Broncode kiezen voor de radioknop 'Aanmaken vanaf URL ' en klik op Volgende.

5. Voer in het Source-instellingenmenu de URL van je API-specificatiebestand in het URL-veld .

6. Klik op API-referentie toevoegen om naar het Finish-scherm te navigeren.

7. Op het Finish-scherm kun je het aantal categorieën en artikelen zien dat is aangemaakt voor je API-specificatiebestand.

8. Klik op Publiceren om je API-documentatie te genereren.

API-documentatie genereren met een CI/CD-flow

Voordat je een API-specificatiebestand uploadt met een CI/CD-flow, zorg ervoor dat de nieuwste versie van Node.js op je systeem is geïnstalleerd. Als je niet bekend bent met Node.js, raadpleeg dan deze handleiding voor installatie-instructies.

Om het API-specificatiebestand te uploaden met een CI/CD-flow,

1. Navigeer naar het gewenste project in het kennisbankportaal.

2. Selecteer API-documentatie ({ }) in de linker navigatiebalk.

3. Klik op het keuzemenu Aanmaken in de bovenste navigatiebalk en selecteer Nieuwe API. Dit toont het referentievenster voor de nieuwe API .

4. Selecteer in het scherm 'Bron' kiezen de CI/CD Flow-radioknop .

5. Kopieer het volledige CLI-commando dat wordt weergegeven vanuit het New API-referentievenster .

6. In het gekopieerde commando werk je de --path waarde bij met:

   • Het volledige pad naar je lokale JSON/YAML/YML spec-bestand. Bijvoorbeeld,

     --path=/Users/yourname/projects/api/openapi.yaml

   • Een geldige URL die naar je API-specificatiebestand verwijst. Bijvoorbeeld,

     --path=https://example.com/api/openapi.yaml

7. Plak het bijgewerkte commando in je terminal en druk op Enter.  

8. Je API-specificatiebestand wordt geüpload en er wordt API-documentatie gegenereerd.

OPMERKING

• De eerste regel (npm install d360 -g) installeert de Document360 CLI-tool. Je hoeft het alleen de eerste keer te draaien. Als het al geïnstalleerd is, kun je die regel overslaan.

• Als je de API-sleutel opnieuw genereert door op het ()-icoon in de UI te klikken, moet je de --apiKey waarde in je CLI-commando bijwerken voordat je het opnieuw uitvoert. De oude sleutel is dan niet langer geldig.

Webhooks beheren (evenementen)

Wanneer je OpenAPI 3.1-specificatie webhooks bevat, importeert Document360 deze en toont een gebeurtenispictogram naast elke webhook. De pagina toont het payloadschema en voorbeeld. Als de specificatie geen voorbeeld bevat, worden een standaardvoorbeeld en een sample-payload getoond. Try It is niet beschikbaar voor webhooks. Webhooks worden opgenomen in resync-operaties en je aangepaste content blijft behouden na regeneratie.

Regenerate API-documentatie

Als je wijzigingen aanbrengt in je API, zoals het toevoegen van nieuwe endpoints, hoef je je API-documentatie niet handmatig in Document360 bij te werken. Je kunt je API-documentatie opnieuw genereren, en eventuele wijzigingen aan je API worden automatisch weergegeven in de bijgewerkte documentatie.

OPMERKING

Alle aangepaste content die je toevoegt aan je API-documentatie blijft behouden wanneer je je API-documentatie opnieuw genereert.

Hergenereer API-documentatie vanaf de URL

1. Navigeer naar het gewenste project in het kennisbankportaal.

2. Selecteer API-documentatie ({ }) in de linker navigatiebalk.

3. Klik op API-referenties in het linker navigatielijstvenster.

4. Klik op het More ()-icoon naast de gewenste API-referentie waarvoor je de API-documentatie wilt regenereren.

   1. Om API-documentatie te regenereren vanuit de bestaande URL:

      • Klik op Resync.

      • De API-documentatie wordt opnieuw gegenereerd volgens het nieuwste API-specificatiebestand.

   

   1. Om API-documentatie te regenereren met een nieuwe URL:

      • Klik op Bewerken.

      • Voer de nieuwe URL in het URL-veld .

      • Klik op Update.

      • De API-documentatie wordt opnieuw gegenereerd volgens het API-specificatiebestand op de nieuwe URL.

Genereer API-documentatie opnieuw uit een API-specificatiebestand

1. Navigeer naar het gewenste project in het kennisbankportaal.

2. Selecteer API-documentatie ({ }) in de linker navigatiebalk.

3. Klik op API-referenties in het linker navigatielijstvenster.

4. Klik op het More ()-icoon naast de gewenste API-referentie waarvoor je de API-documentatie wilt regenereren.

5. Klik Edit.

6. Upload het nieuwste API-specificatiebestand in JSON/YAML/YML-formaat.

7. Klik op Update. De API-documentatie wordt opnieuw gegenereerd volgens het nieuwste API-specificatiebestand.

Regenereer API-documentatie geïntegreerd met CI/CD-flow

Je kunt de API-referentie opnieuw synchroniseren in je CI/CD-pijplijnen met behulp van je d360 npm-pakketten. D360 is de commandoregeltool die je helpt bij het opzetten van workflows die je API-documenten synchroniseren met Document360.

Je kunt de hersynchronisatie ook handmatig uitvoeren met het onderstaande commando.

d360 apidocs:resync 
                    --apiKey=API_key_value
                    --userId=user_id_value
                    --apiReferenceId=API_reference_value
                    --path=Spec_file_path

Download API-referentie

OPMERKING

Om de API-bestanden te downloaden, zorg ervoor dat de referentieschakelaar 'Toon download API' in de instellingen van het kennisbankportaal is ingeschakeld.

Probleemoplossing

Ontbrekende of onjuiste server-URL in OpenAPI

 Fout: Deze fout treedt op wanneer de server-URL ontbreekt of verkeerd is geconfigureerd in de OpenAPI-specificatie. Daardoor weten API-gebruikers niet waar ze API-verzoeken naartoe moeten sturen, en de knop "Probeer het" is mogelijk niet beschikbaar in de API-documentatie. De hoofdoorzaak is meestal een ontbrekend of onjuist servers onderdeel in de OpenAPI-specificatie.

Stappen om op te lossen

Om dit probleem op te lossen, zorg ervoor dat de OpenAPI-specificatie de juiste server-URL bevat:

1. Definieer de server-URL in de OpenAPI-specificatie:

   servers:
     - url: https://apihub.document360.io
       description: Main API hub

2. Voor regio-gebaseerde API's, definieer meerdere server-URL's:

   servers:
     - url: https://apihub.document360.io
       description: Global API hub
     - url: https://apihub.us.document360.io
       description: US region API hub

3. Zorg ervoor dat alle API-clients (bijv. Postman, cURL) de juiste server-URL gebruiken bij het indienen van verzoeken.

OPMERKING

De bovenstaande URL's zijn voorbeelden. Raadpleeg uw specifieke API-configuratie voor de juiste server-URL.

Voorbeeld:

YAML-voorbeeld voor ontbrekende servers   Sectie:

paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    userId:
                      type: integer
                    userName:
                      type: string

Om dit probleem te voorkomen, zorg ervoor dat de servers sectie correct gedefinieerd is in de OpenAPI-specificatie om te voorkomen dat API-gebruikers API-verzoek-URL's handmatig hoeven te construeren.

401 ongeautoriseerde fout door onjuiste server-URL

Fout: Deze fout treedt op wanneer API-verzoeken een 401-ongeautoriseerde reactie teruggeven. Dit gebeurt meestal wanneer de verkeerde server-URL wordt gebruikt bij API-verzoeken. Bijvoorbeeld, het gebruik van https://apihub.document360.io in plaats van https://apihub.us.document360.io veroorzaakt authenticatiefouten.

Stappen om op te lossen:

Om dit probleem op te lossen, volgt u deze stappen om het juiste gebruik van server-URL's en de juiste authenticatie te waarborgen:

1. Zorg ervoor dat API-verzoeken het juiste regio-gebaseerde eindpunt gebruiken.

2. Bevestig dat de juiste client ID en client secret worden gebruikt.

Voorbeeld van een correct API-verzoek:

GET https://apihub.us.document360.io/v2/Articles/{article_id}/en?appendSASToken=true

OPMERKING

De bovenstaande URL is een voorbeeld. Raadpleeg uw specifieke API-configuratie voor de juiste server-URL.

3. Zorg ervoor dat het authenticatietoken correct is opgenomen in de verzoekheaders.

Ontbrekende server-URL in API-documentatie

Fout: Dit probleem doet zich voor wanneer API-gebruikers niet zeker weten welke basis-URL ze voor hun verzoeken moeten gebruiken. Dit gebeurt meestal wanneer de documentatie de server-URL niet duidelijk vermeldt, ook al is deze mogelijk correct geconfigureerd in de OpenAPI-specificatie.

Stappen om op te lossen:

Om verwarring te voorkomen en ervoor te zorgen dat API-gebruikers de juiste basis-URL kennen:

1. Specificeer expliciet de basis-URL in de API-documentatie.

Voorbeelden:

Vergelijkingstabel: server-URL aanwezig versus ontbrekend

OPMERKING

De bovenstaande URL's zijn voorbeelden. Raadpleeg uw specifieke API-configuratie voor de juiste server-URL.

Om dit probleem te voorkomen, zorg ervoor dat de API-documentatie duidelijk de server-URL specificeert om verwarring te voorkomen.

403-fout bij gebruik van de "Try it"-functie met een OAS-bestand

Fout:

Na het succesvol uploaden van een OAS-bestand resulteert het klikken op de Probeer het-functie voor een 403-fout. Deze fout ontstaat wanneer het OAS-bestand een definitie mist voor het beveiligingsmechanisme van BearerAuth .

Stappen om op te lossen:

Om de 403-fout op te lossen, volgt u deze stappen:

1. Controleer of de BearerAuth-beveiligingsdefinitie aanwezig is in je OAS-bestand.

2. Als de BearerAuth-definitie ontbreekt, voeg dan de BearerAuth-beveiligingsdefinitie toe aan het OAS-bestand en upload deze opnieuw.

3. Controleer tijdens het importproces of er meldingen met betrekking tot Bearer-authenticatie worden geactiveerd en richt deze dienovereenkomstig aan.

Onjuiste HTML-styling in API-antwoord

Bij het ophalen van de HTML-inhoud van een artikel via een API wordt het antwoord opgemaakt in JSON, dat gebruikmaakt van escaping (\") om bepaalde tekens veilig te behandelen. Dit ontsnappen verandert tekens zoals citaten, backslashes en nieuwe regels om fouten in datatransmissie te voorkomen. Als de ontsnapte tekens echter niet terug worden omgezet (niet ontsnapt), kan de HTML-structuur breken, wat leidt tot stylingproblemen bij het renderen.

Bijvoorbeeld, een eenvoudige HTML-paragraaf:

<p>This is a "sample" paragraph.</p>

Kan in de JSON-reactie verschijnen als:

"<p>This is a \"sample\" paragraph.</p>"

De ontsnapte dubbele aanhalingstekens (\") zorgen ervoor dat de JSON geldig blijft, maar als deze niet wordt geescaped, kan de HTML niet correct worden weergegeven.

Stappen om op te lossen

1. Haal de HTML-inhoud op via de API en bekijk het antwoord.

2. Zoek naar ontsnapte personages in de JSON-reactie, zoals:

   • \" (ontsnapte dubbele aanhalingstekens)

   • \\ (ontsnapte terugslagen)

   • \n (nieuwregel)

   • \t (tab)

3. Unescape de JSON-inhoud voordat je het rendert. Dit zal de oorspronkelijke HTML-structuur herstellen.

4. Controleer de styling na het unescapen om te zorgen dat de inhoud correct overkomt.

5. Als het probleem blijft bestaan, controleer dan of extra wijzigingen in je code de API-respons veranderen.

   

   Zodra de HTML correct is ontescaped, wordt het weergegeven zoals verwacht, waardoor stijlverschillen worden voorkomen.

Variabelen en snippets worden niet weergegeven in API-respons

Bij het ophalen van artikelinhoud via de API kunnen variabelen en fragmenten onverwerkt verschijnen (bijvoorbeeld {{variable.UserName}} in plaats van daadwerkelijke waarden). Dit gebeurt meestal wanneer de "isForDisplay" parameter niet correct is ingesteld.

• Als "isForDisplay" = true, zal de API de artikelinhoud teruggeven met alle variabelen en fragmenten volledig weergegeven. Dit betekent dat de tijdelijke waarden worden vervangen door daadwerkelijke waarden, waardoor de inhoud geschikt is om aan eindgebruikers te tonen.

• Als "isForDisplay" = false (of niet), zal de API-respons onverwerkte variabelen en fragmenten bevatten, die mogelijk niet nuttig zijn voor directe weergave.

  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

Artikelinhoud in de kennisbank:

Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}.

API-respons zonder "isForDisplay":

"Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}."

De variabelen blijven onverwerkt, waardoor het ongeschikt is voor directe weergave.

API-respons met "isForDisplay"=true:

"Welcome, John! Here’s how to use Document360."

Stappen om op te lossen:

1. Haal de inhoud van het artikel op via de API en bekijk het antwoord.

2. Controleer of variabelen of fragmenten onverwerkt zijn in de reactie.

3. Zorg ervoor dat het API-verzoek de "isForDisplay" parameter bevat. Als het ontbreekt, pas het verzoek dan aan om op te nemen "isForDisplay": true.

4. Stuur het aangepaste API-verzoek. Voorbeeldverzoek:

   {
     "articleId": "12345",
     "isForDisplay": true
   }

5. Controleer of de API-respons nu de correct weergegeven variabelen en snippets weergeeft.

6. Als het probleem blijft bestaan, zorg er dan voor dat het systeem dat de API-respons verwerkt de gerenderde inhoud correct afhandelt en weergeeft.

7. Bij het bijwerken van artikelen via de API, geef geen volledig gerenderde inhoud door om te voorkomen dat dynamische plaatsvervangers door statische waarden worden vervangen.

Lege inhoud getoond in API-documentatie vanwege ontbrekend schematype

De API-documentatie toont een leeg lichaam. De mogelijke oorzaak van deze fout kan zijn dat het OpenAPI-schema het “type": "object” attribuut mist in één of meer objectdefinities.

Stappen om op te lossen:

Zorg ervoor dat elke objectdefinitie in je OpenAPI-specificatie bevat “type": "object”. Dit attribuut specificeert duidelijk dat de gedefinieerde structuur een object is, wat helpt om duidelijkheid en consistentie in je API-documentatie te behouden. Het stelt API-documentatietools in staat om requestbodyparameters, responsschema's en andere objectdefinities nauwkeurig weer te geven, waardoor ontwikkelaars je API makkelijker kunnen begrijpen en ermee te interageren.

Probleem bij het toevoegen van een API-referentie

Fout: API-referentie kan niet worden toegevoegd. Deze operatie kan niet worden voltooid. Zorg er alstublieft voor dat u een geldig specificatiebestand heeft opgeleverd.

De mogelijke oorzaak kan zijn dat het geüploade specificatiebestand (YAML) misvormd is en geen geldige OpenAPI 3.0 YAML is. Dit gebeurt vaak wanneer het bestand wordt gekopieerd of geëxporteerd vanuit een rich-text editor, wat opmaakproblemen veroorzaakt.

Stappen om op te lossen:

1. Valideer je specificatiebestand: Open je YAML-bestand in een tool zoals Swagger Editor of een code-editor om fouten of opmaakfouten te controleren.

2. Let op ongewenste opmaaktekens: Controleer op tekens zoals \f0\fs24 of aanhoudende backslashes \ die mogelijk zijn toegevoegd tijdens copy-paste van een rich-text bron. Deze kunnen het YAML-formaat breken.

3. Maak het bestand schoon: Gebruik een gewone tekst- of code-editor om speciale opmaaktekens te verwijderen. Vermijd het gebruik van tekstverwerkers bij het bewerken of opslaan van YAML-bestanden.

4. Upload het bestand opnieuw: Nadat je het bestand hebt opgeschoond en hebt gecontroleerd of het een geldige OpenAPI 3.0 YAML is, probeer het opnieuw te uploaden.

Handige links