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 de API-documentatie wordtgegenereerd.

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

Inzicht in het verwijderen van eindpunten tijdens resync

Wanneer je je API-specificatiebestand bijwerkt, worden alle endpoints die niet meer in de nieuwe specificatie staan permanent verwijderd, samen met alle aangepaste content die aan die endpointpagina's is toegevoegd.

Om je API-specificatiebestand bij te werken:

1. Upload het bijgewerkte API-specificatiebestand naar het referentievenster API-bewerken .

2. Als eindpunten worden verwijderd, wordt er een waarschuwing weergegeven. Klik op Verwijderde eindpunten tonen om de lijst van getroffen eindpunten te bekijken.

3. Selecteer het vakje 'Bevestigen om door te gaan ' om de verwijdering te bevestigen.

4. Klik op Update om verder te gaan.

Verwijderde eindpunten worden naar de prullenbak verplaatst, waar ze tot 30 dagen kunnen worden bekeken, maar niet kunnen worden hersteld.

 OPMERKING

Als je het resync API-endpoint programmatisch gebruikt, stuur ForceImport = false dan je verzoek in om de lijst met verwijderde endpoints te bekijken zonder verder te gaan met de verwijdering. Stuur ForceImport = true om te bevestigen en ga door.

Download API-bron

OPMERKING

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

Handige links