API-documentatie beheren

Plannen ter ondersteuning van API documentatie

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

API-documentatie genereren

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

• Van een URL

• Vanuit een JSON/YAML-bestand

• Met een CI/CD-stroom

NOTITIE

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

API-documentatie genereren op basis van een API-specificatiebestand

Als u API-verwijzingen wilt genereren op basis van een API-specificatiebestand (JSON/YAML/YML),

1. Navigeer naar het gewenste project in de Knowledge base portal.

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

3. Klik op de vervolgkeuzelijst Maken in de bovenste navigatiebalk en selecteer Nieuwe API. Hiermee wordt het referentievenster Nieuwe API weergegeven.

4. Selecteer de optie API-definitie uploaden in het venster Nieuwe API-referentie .

5. Klik op Uploaden vanaf mijn apparaat of Kiezen uit Drive om het bestand op uw apparaat of Document360 Drive te selecteren. U kunt uw bestand ook rechtstreeks naar het referentievenster Nieuwe API slepen en neerzetten.

Als uw geüploade bestand bijbehorende waarschuwingen of waarschuwingen bevat, kunt u deze bekijken door de vervolgkeuzelijsten Waarschuwingen en waarschuwingen uit te vouwen die worden weergegeven in het referentievenster Nieuwe API.

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

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

NOTITIE

Als u uw documentatie wilt controleren voordat u deze publiceert, klikt u op Sluiten om terug te keren naar het scherm Documentatie. Uw concept is zichtbaar in het deelvenster Categorieën en artikelen .

API-documentatie genereren op basis van een URL

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

1. Navigeer naar het gewenste project in de Knowledge base portal.

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

3. Klik op de vervolgkeuzelijst Maken in de navigatiebalk bovenaan en selecteer Nieuwe API of klik op de knop Nieuwe API in de rechterbovenhoek. Hiermee wordt het referentiepaneel Nieuwe API weergegeven.

4. Selecteer in het scherm Bron kiezen het keuzerondje Maken van URL en klik op Volgende.

5. Voer in het scherm Broninstellingen de URL voor uw API-specificatiebestand in het URL-veld in.

6. Klik op API-verwijzing toevoegen om naar het scherm Voltooien te navigeren.

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

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

NOTITIE

Als u uw API-documentatie wilt verifiëren voordat u deze publiceert, klikt u op Sluiten op het scherm Voltooien om terug te keren naar het scherm Documentatie. U kunt de concepten van uw API-documentatie bekijken in het deelvenster Categorieën en artikelen .

API-documentatie genereren met een CI/CD-flow

Voordat u een API-specificatiebestand met een CI/CD-stroom uploadt, moet u ervoor zorgen dat de nieuwste versie van Node.js op uw systeem is geïnstalleerd. Als u niet bekend bent met Node.js, raadpleeg dan this guide voor installatie-instructies.

Als u het API-specificatiebestand wilt uploaden met een CI/CD-stroom,

1. Navigeer naar het gewenste project in de Knowledge base portal.

2. Selecteer API-documentatiop ({ }) in de linkernavigatiebalk.

3. Klik op de vervolgkeuzelijst Maken in de bovenste navigatiebalk en selecteer Nieuwe API. Hiermee wordt de pop-up Nieuwe API-referentie weergegeven.

4. Selecteer in het scherm Bron kiezen de keuzerondje CI/CD Flow en klik op Volgende.

5. Kopieer de volledige CLI-opdracht die wordt weergegeven in de pop-up Nieuwe API-referentie.

6. Werk in de gekopieerde opdracht de --path waarde bij met:

   • Het volledige pad naar uw lokale JSON/YAML/YML-specificatiebestand. Bijvoorbeeld

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

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

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

7. Plak de bijgewerkte opdracht in uw terminal en druk op Enter.  

8. Uw API-specificatiebestand wordt geüpload en API-documentatie wordtgegenereerd.

NOTITIE

• De eerste regel (npm install d360 -g) installeert de Document360 CLI tool. U hoeft het alleen de eerste keer uit te voeren. Als het al is geïnstalleerd, kunt u die regel overslaan.

• Als u de API-sleutel opnieuw genereert door op het pictogram () in de gebruikersinterface te klikken, moet u de --apiKey waarde in uw CLI-opdracht bijwerken voordat u deze opnieuw uitvoert. De oude sleutel is dan niet meer geldig.

API-documentatie opnieuw genereren

Als u wijzigingen aanbrengt in uw API, zoals het toevoegen van eindpunten, hoeft u uw API-documentatie in Document360 niet handmatig bij te werken. U kunt uw API-documentatie eenvoudig opnieuw genereren en eventuele wijzigingen in uw API worden automatisch weergegeven in de API-documentatie.

NOTITIE

Alle aangepaste inhoud die u aan uw API-documentatie toevoegt, blijft behouden wanneer u uw API-documentatie opnieuw genereert.

API-documentatie opnieuw genereren op basis van de URL

1. Navigeer naar het gewenste project in de Knowledge base portal.

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

3. Klik op verwijzing naar API-documenten in het linkerdeelvenster met navigatielijst.

4. Klik op het pictogram Meer () naast de gewenste API-referentie waarvoor u de API-documentatie opnieuw wilt genereren.

   1. API-documentatie opnieuw genereren op basis van de bestaande URL:

      • Klik op Opnieuw synchroniseren.

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

   2. API-documentatie opnieuw genereren met een nieuwe URL:

      • Klik op Bewerken.

      • Voer de nieuwe URL in het URL-veld in.

      • Klik op Bijwerken.

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

API-documentatie opnieuw genereren op basis van een API-specificatiebestand

1. Navigeer naar het gewenste project in de Knowledge base portal.

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

3. Klik op verwijzing naar API-documenten in het linkerdeelvenster met navigatielijst.

4. Klik op het pictogram More () naast de gewenste API-referentie waarvoor u de API-documentatie opnieuw wilt genereren.

5. Klik op Edit.

6. Upload het meest recente API-specificatiebestand in JSON/YAML-indeling.

7. Klik op Bijwerken. De API-documentatie wordt opnieuw gegenereerd volgens het meest recente API-specificatiebestand.

API-documentatie opnieuw genereren die is geïntegreerd met CI/CD-stroom

U kunt de API-referentie in uw CI/CD-pijplijnen opnieuw synchroniseren met behulp van uw d360 npm-pakketten. D360 is de opdrachtregeltool die u helpt bij het instellen van workflows die uw API-documenten synchroniseren met Document360.

U kunt de hersynchronisatie ook handmatig uitvoeren met behulp van de onderstaande opdracht.

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

API-referentie downloaden

NOTITIE

Als u de API-bestanden wilt downloaden, moet u ervoor zorgen dat de wisselknop voor API-referentie weergeven in de instellingen van de Knowledge Base-portal is ingeschakeld.

Probleemoplossing

Ontbrekende of onjuiste server-URL in OpenAPI

Fout: Deze fout treedt op wanneer de server-URL ontbreekt of onjuist is geconfigureerd in de OpenAPI-specificatie. Als gevolg hiervan weten API-gebruikers niet waar ze API-verzoeken naartoe moeten sturen en is de knop "Probeer het" mogelijk niet beschikbaar in de API-documentatie. De hoofdoorzaak is meestal een ontbrekende of onjuiste servers sectie in de OpenAPI-specificatie.

Stappen om op te lossen

Om dit probleem op te lossen, moet u ervoor zorgen 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. Definieer voor API's op basis van regio's 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 (Postman, cURL, enz.) de juiste server-URL gebruiken bij het indienen van aanvragen.

NOTITIE

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

Voorbeeld:

YAML-voorbeeld voor ontbrekend servers afdeling:

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, moet u ervoor zorgen dat de servers sectie is correct gedefinieerd in de OpenAPI-specificatie om te voorkomen dat API-gebruikers handmatig API-aanvraag-URL's moeten maken.

401 ongeautoriseerde fout door onjuiste server-URL

Fout: Deze fout treedt op wanneer API-verzoeken een 401-onbevoegd antwoord retourneren. Dit gebeurt meestal wanneer de onjuiste server-URL wordt gebruikt in API-verzoeken. Het gebruik in https://apihub.document360.io plaats van https://apihub.us.document360.io veroorzaakt bijvoorbeeld verificatiefouten.

Stappen om op te lossen:

Volg deze stappen om dit probleem op te lossen om ervoor te zorgen dat het gebruik van de server-URL en de juiste verificatie correct zijn:

1. Zorg ervoor dat API-aanvragen het juiste eindpunt op basis van de regio gebruiken.

2. Controleer of de juiste client-ID en het juiste clientgeheim worden gebruikt.

Voorbeeld van een correct API-verzoek:

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

NOTITIE

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

3. Zorg ervoor dat het verificatietoken correct is opgenomen in de aanvraagheaders.

Ontbrekende server-URL in API-documentatie

Fout: Dit probleem treedt op wanneer API-gebruikers niet zeker weten welke basis-URL ze moeten gebruiken voor hun aanvragen. 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. Geef de basis-URL expliciet op in de API-documentatie.

Voorbeelden:

Vergelijkingstabel: server-URL aanwezig vs. ontbrekend

NOTITIE

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

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

403-fout bij gebruik van de functie "Probeer het" met een OAS-bestand

Fout:

Nadat u een OAS-bestand met succes hebt geüpload, resulteert het klikken op de functie Probeer het in een 403-fout. Deze fout treedt op wanneer in het OAS-bestand een definitie voor het BearerAuth-beveiligingsmechanisme ontbreekt.

Stappen om op te lossen:

Volg deze stappen om de 403-fout op te lossen:

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

2. Als de BearerAuth-definitie ontbreekt, neemt u de BearerAuth-beveiligingsdefinitie op in het OAS-bestand en uploadt u deze opnieuw.

3. Controleer tijdens het importproces of er waarschuwingen met betrekking tot Toonderverificatie worden geactiveerd en beantwoord deze dienovereenkomstig.

Onjuiste HTML-opmaak in API-respons

Bij het ophalen van de HTML-inhoud van een artikel via een API, wordt het antwoord opgemaakt in JSON, dat escapeping (\") gebruikt om bepaalde tekens veilig te verwerken. Deze escapeping wijzigt tekens zoals aanhalingstekens, backslashes en nieuwe regels om fouten bij de gegevensoverdracht te voorkomen. Als de escape-tekens echter niet worden geconverteerd (unescaped), kan de HTML-structuur breken, wat leidt tot opmaakproblemen bij het renderen.

Bijvoorbeeld een eenvoudige HTML-alinea:

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

Kan in het JSON-antwoord worden weergegeven als:

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

De dubbele aanhalingstekens (\") zorgen ervoor dat de JSON geldig blijft, maar als er geen escaped is, wordt de HTML mogelijk niet correct weergegeven.

Stappen om op te lossen

1. Haal de HTML-inhoud op via de API en inspecteer de respons.

2. Zoek naar escapetekens in het JSON-antwoord, zoals:

   • \" (ontsnapte dubbele aanhalingstekens)

   • \\ (ontsnapte backslashes)

   • \n (nieuwe regel)

   • \t (tabblad)

3. Maak de JSON-inhoud ongedaan voordat u deze rendert. Hiermee wordt de oorspronkelijke HTML-structuur hersteld.

4. Controleer de stijl na het ongedaan maken van de escapecode om er zeker van te zijn dat de inhoud correct wordt weergegeven.

5. Als het probleem zich blijft voordoen, controleert u of aanvullende wijzigingen in uw code de API-reactie wijzigen.

   

   Zodra de HTML op de juiste manier is uitgeschakeld, wordt deze weergegeven zoals verwacht, waardoor stijlverschillen worden voorkomen.

Variabelen en fragmenten worden niet weergegeven in API-respons

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

• Als "isForDisplay" = true, retourneert de API de artikelinhoud met alle variabelen en fragmenten volledig gerenderd. Dit betekent dat de tijdelijke aanduidingen worden vervangen door werkelijke waarden, waardoor de inhoud geschikt is voor weergave aan eindgebruikers.

• Als "isForDisplay" = false (of niet ingesteld), bevat de API-respons onverwerkte variabelen en fragmenten, 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

Inhoud van het artikel 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 API en inspecteer de respons.

2. Controleer of variabelen of fragmenten onverwerkt worden weergegeven in het antwoord.

3. Zorg ervoor dat het API-verzoek de "isForDisplay" parameter bevat. Als het ontbreekt, wijzigt u het verzoek om "isForDisplay": true.

4. Verzend het gewijzigde API-verzoek. Voorbeeld aanvraag:

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

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

6. Als het probleem zich blijft voordoen, controleert u of het systeem dat de API-respons verwerkt, de gerenderde inhoud correct verwerkt en weergeeft.

7. Wanneer u artikelen via de API bijwerkt, mag u geen volledig gerenderde inhoud doorgeven om te voorkomen dat dynamische tijdelijke aanduidingen worden vervangen door statische waarden.

Lege body weergegeven in API-documentatie vanwege ontbrekend schematype

In de API-documentatie wordt een lege body weergegeven. De mogelijke oorzaak van deze fout kan zijn dat het kenmerk in een “type": "object” of meer objectdefinities ontbreekt in het OpenAPI-schema.

Stappen om op te lossen:

Zorg ervoor dat elke objectdefinitie in uw OpenAPI-specificatie . “type": "object” Dit kenmerk geeft duidelijk aan dat de gedefinieerde structuur een object is, waardoor de duidelijkheid en consistentie in uw API-documentatie behouden blijft. Het stelt API-documentatietools in staat om querybody-parameters, antwoordschema's en andere objectdefinities nauwkeurig weer te geven, waardoor het voor ontwikkelaars gemakkelijker wordt om uw API te begrijpen en ermee te werken.

Handige links