Deze gids leidt je bij het publiceren van je eerste API-referentie in Document360, vanaf het uploaden van je specificatiebestand naar een live, interactief ontwikkelaarsportaal.
Aan het einde van dit artikel heb je:
- Een API-referentie gegenereerd vanuit je OpenAPI-specificatie
- Je eindpunten zijn zichtbaar en doorbladerbaar voor ontwikkelaars
- De Try It! interactieve console klaar voor live API-testen
API-documentatie is beschikbaar voor alle betaalde abonnementen. Elk betaald abonnement bevat één API-werkruimte. Extra werkplekken kunnen als add-ons worden aangeschaf.
Vereisten
Zorg ervoor dat je voor het begin het volgende hebt:
- Een Document360-account op een professioneel, zakelijk of ondernemingsplan.
- Een API-specificatiebestand in een van deze formaten: OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1, of Postman Collection. Geaccepteerde bestandstypen zijn JSON, YAML of YML.
- Toegang tot het kennisbankportaal met rechten om content te maken.
Als je nog geen specificatiebestand hebt, kun je deze gids nog steeds volgen met het voorbeeld van de Pet Store API-bestand dat Document360 aanbiedt. Je wordt tijdens de installatie gevraagd het te gebruiken.
Ga naar het API-documentatiewerkgebied
- Log in op Document360 en open je project in het kennisbankportaal.
- Klik in de linker navigatiebalk op API-documentatie
{ }. Dit opent de dedicated API-werkruimte, los van je standaard kennisbank. - Klik in de bovenste navigatiebalk op het keuzemenu Aanmaken en selecteer Nieuwe API. Dit opent het referentievenster Nieuwe API.
Je kunt maximaal 3 API-referenties maken binnen elke API-werkruimte.
Kies hoe je je specificatie importeert
Document360 ondersteunt twee manieren om je specificatiebestand te importeren: bestanden uploaden en URL-import. De CI/CD-stroom is geen aparte importmethode; Het is een manier om een van deze twee methoden te automatiseren, zodat je documentatie automatisch wordt bijgewerkt wanneer je specificatie verandert.
| Methode | Wanneer te gebruiken | Hoe het werkt |
|---|---|---|
| Bestandsupload | Je hebt het specificatiebestand lokaal als JSON, YAML of YML. | Upload het bestand direct. Het beste om snel te beginnen of voor zeldzame updates. |
| URL-import | Je specificatie wordt gehost op een stabiele publieke of interne URL. | Wijs Document360 naar de URL. Je kunt handmatig opnieuw synchroniseren vanaf dezelfde URL telkens wanneer de specificatie verandert. |
| CI/CD-stroom | Je wilt dat de documentatie automatisch wordt bijgewerkt bij elke specificatiewijziging. | Automatiseert het uploaden van bestanden of URL-import via de d360 CLI in je pipeline. Vereist Node.js. |
Upload je specificatie
Upload een bestand
- Selecteer in het referentievenster Nieuwe API de optie Upload API-definitie .
- Klik op Uploaden vanaf mijn apparaat of sleep en laat je bestand vallen. Ondersteunde formaten: JSON, YAML, YML.
- Document360 ontleedt het bestand en genereert automatisch de API-referentie. Als waarschuwingen worden gedetecteerd, verschijnt er een sectie Waarschuwingen en Waarschuwingen — vergroot deze om ze te bekijken. Je kunt later volledige details bekijken in het Logs-gedeelte.
- Klik op Nieuwe API-referentie om verder te gaan.
Importeren vanaf een URL
- Selecteer in het referentievenster Nieuwe API de optie 'Aanmaken vanaf URL' en klik op Volgende.
- Voer de URL in die naar je OpenAPI-specificatiebestand wijst in het URL-veld.
- Document360 haalt de specificatie op en verwerkt ze. Als waarschuwingen worden gedetecteerd, zijn deze beschikbaar in het Logs-gedeelte na import.
- Klik op API-referentie toevoegen om verder te gaan.
Gebruik de CI/CD-flow
Deze optie vereist dat Node.js op je systeem wordt geïnstalleerd.
- Selecteer in het New API-referentievenster de CI/CD Flow-optie .
- Kopieer het volledige CLI-commando dat in het venster wordt weergegeven.
- In het gekopieerde commando vervang je de
--pathwaarde door het volledige pad naar je lokale specificatiebestand of een geldige URL die ernaar verwijst. Bijvoorbeeld:
--path=/Users/yourname/projects/api/openapi.yaml
Of een URL:
--path=https://example.com/api/openapi.yaml
- Plak het bijgewerkte commando in je terminal en druk op Enter. Document360 uploadt je specificatie en genereert de API-documentatie.
De eerste regel van het CLI-commando (npm install d360 -g) installeert de Document360 CLI-tool. Je hoeft het maar één keer te draaien. Als het al geïnstalleerd is, kun je die regel overslaan.
Als je je API-sleutel opnieuw genereert, moet je de --apiKey waarde in je CLI-commando bijwerken voordat je het opnieuw uitvoert. De oude sleutel is dan niet langer geldig.
Geen specificatiebestand? Gebruik de voorbeeld van de Pet Store API
Als je geen specificatiebestand klaar hebt, selecteer dan Try sample Pet Store API-bestand als je erom vraagt. Document360 maakt automatisch een voorbeeld van een API-referentie aan in conceptmodus. Je kunt het verkennen en later vervangen door je eigen specificatie.
Bekijk waarschuwingen en waarschuwingen
Na het uploaden van je specificatie toont Document360 je een samenvatting van hoeveel categorieën en artikelen er zijn aangemaakt, samen met eventuele waarschuwingen of waarschuwingen die in je bestand zijn gedetecteerd.
- Waarschuwingen en waarschuwingen betekenen dat de specificatie is geïmporteerd, maar sommige elementen worden mogelijk niet weergegeven zoals verwacht. Je kunt de volledige details bekijken in de sectie Logs: ga naar je API-referentie, klik op het Meer-icoon
(⋯)en selecteer Logs. - Fouten betekenen dat de import mislukte. De meest voorkomende oorzaak is een niet-ondersteund bestandsformaat of een ongeldige URL. Vervang het bestand of corrigeer de URL en probeer het opnieuw.
Publiceer je API-referentie
Nadat je spec succesvol is verwerkt:
- Een bevestigingsvenster toont het aantal aangemaakte categorieën en artikelen. Klik op Publiceren om de API-referentie live te maken.
- Als je de inhoud wilt bekijken voordat je publiceert, klik dan op Sluiten. Je API-referentie wordt opgeslagen in conceptmodus en zichtbaar in het Categorieën & Artikelen-paneel.
Conceptmodus is handig als je aangepaste inhoud wilt toevoegen aan individuele endpoint-artikelen voordat je ze openbaar maakt. Alle aangepaste content die je toevoegt, blijft bewaard wanneer je je documentatie opnieuw genereert of synchroniseert.
Configureer authenticatie voor Try It!
De Try It!-console laat ontwikkelaars je API-endpoints direct uit de documentatie testen. Om correct te werken, moet de authenticatiemethode in je specificatie worden gedefinieerd en geconfigureerd in Document360.
Document360 ondersteunt de volgende authenticatiemethoden:
| Methode | Hoe het werkt |
|---|---|
| Basisauthenticatie | Gebruikersnaam en wachtwoord zijn doorgegeven in de requestheader. |
| Dragertoken | Een token dat na het inloggen werd gegenereerd, werd doorgegeven in de autorisatieheader. |
| API-sleutel | Een unieke sleutel die in de requestheaders werd doorgegeven. |
| OAuth2 | Ondersteunt autorisatiecode, PKCE, clientgegevens en impliciete stromen. |
| OpenID Connect | Breidt OAuth2 uit om gebruikersidentiteitsverificatie toe te voegen. |
De Try It!-console ondersteunt meerdere beveiligingsschema's tegelijkertijd, waardoor het testen van eindpunten mogelijk is die gecombineerde authenticatiemethoden vereisen.
OAuth2 en OpenID Connect: aanvullende configuratie
Bij gebruik van OAuth2 of OpenID Connect zijn twee instellingen vereist:
- Redirect URI — Stel dit in je OAuth-provider in op
domain/oauth. Bijvoorbeeld:https://apidocs.yourdomain.com/oauth. - Stille verlenging — Document360 verst automatisch het autorisatietoken op de achtergrond tijdens actieve Try It!-sessies, zodat gebruikers niet handmatig opnieuw hoeven te authenticeren.
Als de Try It!-knop niet zichtbaar is op je kennisbanksite, controleer dan of zowel de servervariabele als de server-URL correct zijn gedefinieerd in je API-specificatiebestand. Zonder deze werkt de Try It!-functie niet.
Stel toegang en privacy voor de lezer in
Bepaal wie je gepubliceerde API-referentie kan zien door de instellingen voor lezerstoegang te configureren.
| Setting | Wat het betekent |
|---|---|
| Privé | Alleen teamaccounts kunnen de API-referentie bekijken. Gebruik voor interne of partner-only API's. |
| Publiek | Iedereen kan de API-referentie zonder authenticatie benaderen. |
| Gemengd | Sommige secties zijn openbaar, andere zijn beperkt tot teamaccounts. |
Om lezerstoegang te configureren, navigeer naar Instellingen > Gebruikers & Rechten > Lezerstoegang in het kennisbankportaal en zoek je je API-documentatiewerkruimte.
Bezoeken /apidocs voordat eindpuntartikelen worden gepubliceerd, geeft een 404-fout — er is nog geen inhoud om te tonen. Dit geldt ook als je een navigatielink /apidocs hebt toegevoegd op je kennisbanksite. Publiceer ten minste één endpoint-artikel voordat je je API-referentie toegankelijk maakt voor lezers.