Aan de slag met API-documentatie

Plannen ter ondersteuning van API-documentatie

De API documentatiefunctie in Document360 biedt een complete oplossing voor het maken en beheren van API-verwijzingen. Met deze functie kunt u API-documentatie van hoge kwaliteit genereren die gebruikers helpt uw API's te begrijpen en er effectief mee te werken. U 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-stroom.

Bovendien kunt u met de functie Try it! in Document360 API-eindpunten rechtstreeks op de Knowledge base sitetesten. De interactieve console op de Knowledge Base-site stelt ontwikkelaars in staat om de benodigde parameters in te voeren en API-aanroepen uit te voeren, waardoor realtime antwoorden worden verkregen. Deze functie is handig om problemen op te lossen en te begrijpen hoe een API zich gedraagt zonder de documentatie te verlaten of code te schrijven.

Onboarding van API-documentatie

Wanneer gebruikers zich aanmelden voor Document360 kiezen ze hun primaire use case in stap 1 van de onboarding-flow. Voor gebruikers die API-documentatie willen maken, biedt Document360 een gestroomlijnde onboarding-ervaring. Als u API-documentatie selecteert als uw use case, wordt u omgeleid naar de API-installatiestroom, waar u API-verwijzingen kunt maken met behulp van de beschikbare opties.

In stap 2 van de onboarding-flow heb je drie opties voor het maken van een API-referentie:

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

• Maken van URL: haalt automatisch de API-specificatie op van de gehoste URL.

• Probeer een voorbeeld-API-bestand voor dierenwinkels: Als u nog geen API-bestand klaar hebt, kunt u het voorbeeldbestand (Dierenwinkel-API) van Document360 gebruiken om uw werkruimte te vullen.

Een API-definitiebestand uploaden

Als u een API-verwijzing wilt maken op basis van een API-definitiebestand, selecteert u het keuzerondje API-bestand uploaden. Klik vervolgens op Uploaden vanaf mijn apparaat of sleep het API-specificatiebestand vanaf uw apparaat.

NOTITIE

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

Het systeem parseert het bestand en genereert automatisch de API-referentie.

• Als er eeny waarschuwingen/waarschuwingen worden gedetecteerd in het geüploade bestand, wordt tijdens de onboarding een overzicht op hoog niveau weergegeven. U kunt diepgaande details bekijken in de Knowledge Base-portal in de sectie logboeken onder Meer opties binnen API-verwijzingen.

• Als er een fout wordt gedetecteerd in het geüploade bestand (bijvoorbeeld - Niet-ondersteunde bestandsindeling), vervangt u het geüploade bestand door een alternatief bestand.

Een URL voor API-documentatie invoeren

Als u een API-verwijzing wilt maken op basis van een API-documentatie-URL, selecteert u het keuzerondje Maken van URL . Voer vervolgens de URL voor uw OpenAPI-bestand in het veld URL naar uw API-definitie in. Document360 haalt de API-structuur op en verwerkt deze. Vergelijkbaar met het uploaden van bestanden,

• Als er waarschuwingen/waarschuwingen worden gedetecteerd, kunt u deze bekijken in de kennisbankportal in de logsectie onder Meer opties binnen API-referenties.

• Als er een fout wordt gedetecteerd (bijvoorbeeld - Ongeldige URL), voert u de geldige URL voor uw OpenAPI-bestand in.

API-instellingen overslaan

Als u de optie Probeer een voorbeeld van een API-bestand voor dierenwinkels kiest,

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

• Dit zal beschikbaar zijn in de conceptmodus. U kunt de eindpunten controleren voordat u het specificatiebestand publiceert of het specificatiebestand uploaden en later publiceren.

Personaliseer uw kennisbank

In stap 3 kunt u de URL van uw voorkeurswebsite invoeren. Als u deze stap wilt overslaan, is het domein standaard het domein dat is gekoppeld aan uw registratie-e-mail.

Richtlijnen voor merken

In stap 4 worden uw projectnaam, standaardtaal, merklogo en merkkleuren automatisch ingesteld op basis van de door u opgegeven URL. U kunt deze velden echter indien nodig bewerken. De taalinstellingen van uw browser bepalen de standaardtaal. Engels wordt standaard geselecteerd als andere talen de taal van uw browser niet ondersteunen.

NOTITIE

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

• Het merklogo en de primaire/secundaire kleuren worden uit uw website gehaald. Als u ervoor kiest om deze stap over te slaan , wordt de projectnaam afgeleid van uw registratie-e-mail en worden het standaardlogo en de standaardkleuren van Document360 toegepast.

Privacy van documentatie instellen

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 werken, zodat deze veilig en intern blijft.

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

• Gemengd: combineer privé- en openbare toegang door sommige secties van de kennisbank zichtbaar te maken voor het publiek, terwijl andere secties beperkt blijven tot alleen teamaccounts.

Klik ten slotte op Volgende om uw API-onboardingstroom te voltooien.

U wordt doorgestuurd naar de API-documentatiewerkruimte, waar:

• U ziet de API-referentie van de API-specificatie die u tijdens de onboarding hebt opgegeven.

• Als u geen API-specificatie hebt opgegeven, is er een voorbeeld-API-referentie (Pet Store-API) beschikbaar in de conceptmodus.  

Autorisatie technieken

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

• Basisverificatie: Vereist een gebruikersnaam en wachtwoord die in de aanvraag worden doorgegeven.

• Token aan toonder: Wordt geverifieerd met een token dat wordt gegenereerd na het inloggen.

• API-sleutel: Gebruikt een unieke sleutel, die wordt doorgegeven in de aanvraagheaders, voor verificatie.

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

• OpenID Connect: breidt OAuth2 uit door verificatie van de gebruikersidentiteit toe te voegen.

Overwegingen bij autorisatie (OAuth2 en OpenID)

Wanneer u werkt met API's die OAuth2 of OpenID gebruiken voor autorisatie, zijn bepaalde instellingen essentieel voor een goede functionaliteit.

• Omleidings-URI: Dit is de URL waarnaar de gebruiker wordt omgeleid na het voltooien van een autorisatiestroom. Zorg ervoor dat u de URI instelt in de indeling: domain/oauth. Bijvoorbeeld: https://apidocs.document360.com/oauth.

• Stille verlenging: Stille vernieuwing vernieuwt automatisch het autorisatietoken op de achtergrond, zodat gebruikers zich niet opnieuw hoeven te verifiëren tijdens hun sessie. Dit houdt hun sessie zonder onderbreking actief. Om te voorkomen dat de autorisatie verloopt tijdens sessies waarin gebruikers communiceren met de functie Try It! , vernieuwt Document360 het vernieuwingstoken automatisch op de achtergrond. Dit zorgt ervoor dat gebruikers zich niet handmatig opnieuw hoeven te authenticeren.

Aankoop

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

1. Navigeer naar () > Knowledge Base-portal > Facturering > Mijn abonnement.

2. Klik op Add-on Kopen.

3. Voeg het gewenste aantal API-documentatiewerkruimten toe. Bekijk de kosten van de add-on en het verschuldigde bedrag.

4. Klik op Betaling bevestigen om door te gaan met de betaling.

Probleemoplossing

Problemen met API-toegang

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

Deze fout treedt op wanneer de openbare API-toegang is gedeactiveerd in de projectinstellingen.

Stappen om op te lossen:

1. Navigeer naar () > AI-functies > Eddy AI in de Knowledge Base-portal.

2. Zorg er in het gedeelte AI-zoeksuite voor dat het selectievakje Openbare API is ingeschakeld.

   

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

Gerelateerde video's

Ervaar onze moderne API-documentatie in Document360 als nooit tevoren

Test API-eindpunten rechtstreeks vanuit documentatie met de functie Probeer het

Extra informatie

Introductie van API-documentatie: verbeter uw API-ervaring - Klik om te lezen