De API-documentatiefunctie van Document360 biedt je een complete, end-to-end oplossing voor het publiceren, beheren en testen van API-referenties. Of je nu een startup bent die je eerste publieke API uitbrengt of een onderneming die tientallen interne microservices onderhoudt, Document360 verandert je OpenAPI-specificatie in gepolijste, interactieve ontwikkelaarsdocumentatie zonder dat er aangepaste tools of handmatige opmaak nodig zijn.
Wat is API-documentatie en waarom is het belangrijk?
API-documentatie is de technische referentie die ontwikkelaars precies vertelt hoe ze met je API moeten omgaan: welke endpoints bestaan, welke parameters ze accepteren, welke antwoorden ze teruggeven en hoe authenticatie werkt. In tegenstelling tot algemene kennisbasisartikelen volgen API-documenten een strikt, gestructureerd formaat dat is afgeleid van een machineleesbaar specificatiebestand.
Waarom het belangrijk is:
- Vermindert de integratietijd. Clear docs verminderen de onboarding van dagen naar uren. Ontwikkelaars besteden minder tijd aan gokken en meer aan bouwen.
- Vermindert de ondersteuningslast. Wanneer de artsen de vragen "hoe authenticeer ik?" en "wat betekent een 422?" beantwoorden, krijgt je team minder tickets.
- Bouwt het vertrouwen van ontwikkelaars op. Onvolledige of verouderde API-documenten duiden op een onbetrouwbaar product. Hoogwaardige documentatie is een direct signaal van productkwaliteit.
- Maakt zelfbediening mogelijk. Externe partners, klanten en externe ontwikkelaars kunnen integreren zonder dat je team hoeft te helpen.
API-documentatie versus gewone documentatie
| Aspect | API-documentatie | Reguliere documentatie |
|---|---|---|
| Primaire doelgroep | Ontwikkelaars en technische integratoren | Eindgebruikers, interne teams |
| Structuur | Aangestuurd door een specificatiebestand (OpenAPI, Postman) | Handmatig geschreven artikelen |
| Inhoudstype | Eindpunten, parameters, schema's, authenticatiemethoden | Gidsen, handleidingen, conceptuele artikelen |
| Interactiviteit | Live testen via Try It! | Statische lezing |
| Versiebeheer | Gekoppeld aan API-specificatieversies | Redactioneel beheerd |
| Auto-generatie | Ja, uit het specificatiebestand | Nee |
In Document360 bevindt API-documentatie zich in een speciale API-werkruimte die gescheiden is van je standaard kennisbank. Dit maakt verschillende toegangscontroles, routering en branding mogelijk voor je content gericht op ontwikkelaars.
Ondersteunde specificatieformaten
Document360 ondersteunt de volgende specificatieformaten:
- OpenAPI 2.0 (voorheen Swagger)
- OpenAPI 3.0
- OpenAPI 3.1 (inclusief webhook-ondersteuning)
- Postbode Collecties
Bestanden kunnen worden geüpload als JSON, YAML of YML.
Als je opnieuw begint, gebruik dan OpenAPI 3.1. Het is de huidige standaard, ondersteunt webhooks native en heeft het rijkste tool-ecosysteem. Als je migreert vanuit een bestaande Swagger 2.0-setup, accepteert Document360 het zoals het is terwijl je incrementeel upgradet.
De Try It!- functie in Document360 stelt je in staat om API-endpoints direct te testen op de Knowledge Base-site. De interactieve console stelt ontwikkelaars in staat de benodigde parameters in te voeren en API-aanroepen uit te voeren, waarbij ze realtime antwoorden krijgen, zonder de documentatie te verlaten of code te schrijven.
De sectie Try It! ondersteunt meerdere beveiligingsschema's tegelijkertijd, waardoor gebruikers eindpunten die gecombineerde authenticatiemethoden vereisen effectiever kunnen testen.
Webhooks in OpenAPI 3.1
Document360 ondersteunt webhooks die zijn gedefinieerd in OpenAPI 3.1. Webhooks verschijnen met een gebeurtenispictogram in je API-referentie en bevatten een payload-sectie gebaseerd op je schema. Als er geen voorbeeld wordt gegeven, toont Document360 een standaardvoorbeeld en een voorbeeldpayload. Try It! is niet beschikbaar voor webhooks. Webhooks worden ondersteund voor bestandsuploads, URL-importen en CI/CD-flows.
Autorisatietechnieken
Bij het interacteren met een API is het belangrijk ervoor te zorgen dat alleen geautoriseerde gebruikers toegang hebben tot bepaalde gegevens of specifieke acties kunnen uitvoeren. Document360 ondersteunt de volgende autorisatiemethoden:
- Basisauthenticatie - Vereist een gebruikersnaam en wachtwoord die in het verzoek worden doorgegeven.
- Bearer token - Authenticeert met een token die na het inloggen wordt gegenereerd.
- API-sleutel - Gebruikt een unieke sleutel, doorgegeven in de requestheaders, voor authenticatie.
- OAuth2 - Beveiligt API's via verschillende stromen: autorisatiecode, PKCE, clientgegevens en impliciet.
- OpenID Connect - Uitbreidt OAuth2 door gebruikersidentiteitsverificatie toe te voegen.
OAuth2 en OpenID Connect: aanvullende configuratie
Bij het werken met API's die OAuth2 of OpenID Connect gebruiken, zijn er twee instellingen nodig om Try It! correct te laten werken:
- Omleiden URI - Stel dit in je OAuth-provider in op het formaat
domain/oauth. Bijvoorbeeld:https://apidocs.document360.com/oauth. - Stille verlenging - Document360 verst automatisch het autorisatietoken op de achtergrond tijdens actieve Try It!-sessies, zodat gebruikers zich niet handmatig hoeven te authenticeren.
FAQ
Hoe verschilt API-documentatie van gewone documentatie?
API-documentatie is specifiek ontworpen om endpoints, authenticatie en integraties uit te leggen. Het staat los van standaard kennisbasisartikelen en is nuttig voor content gericht op ontwikkelaars.
Wat is een API-referentie?
Een API-referentie is een documentatiebron die uitgebreide informatie biedt over de functies, klassen, methoden, parameters, retourtypes en andere componenten van een API. Het is een gids of handleiding voor ontwikkelaars die de API willen integreren of gebruiken in hun applicaties.
Wat zijn de ondersteunde specificatiebestandsformaten?
Je kunt je specificatiebestand uploaden als een URL-, JSON-, YAML- of YML-bestand . Document360 ondersteunt OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 en Postman API-specificaties.
Hoeveel API-referenties kan ik maken?
Binnen elke API-werkruimte kun je maximaal 3 API-referenties aanmaken.
Wat is de standaardvolgorde van categorieën bij het uploaden van een OpenAPI-specificatiebestand?
Categorieën in Document360 worden aangemaakt op basis van de tagvolgorde die in je specificatiebestand is gedefinieerd. Als je specificatie bijvoorbeeld tags definieert in de volgorde Huisdier, Winkel, Gebruiker — verschijnen de categorieën in diezelfde volgorde.
De optie "Probeer het!" is niet beschikbaar op de Knowledge Base-site. Wat zou de reden kunnen zijn?
Als de Try It!- functie niet zichtbaar is, zorg er dan voor dat zowel de servervariabele als de server-URL correct zijn gedefinieerd in je API-specificatiebestand. Zonder deze functies werkt de functie niet.
Kunnen API-referentie dropdown-waarden via de UI worden aangepast?
Nee. Wijzigingen aan API-referentie-elementen zoals dropdownwaarden kunnen alleen worden aangebracht via het OpenAPI-specificatiebestand. Het wijzigen van deze waarden via de UI wordt momenteel niet ondersteund.
Gerelateerde video's
Ervaar onze moderne API-documentatie in Document360
Test API-endpoints direct uit documentatie met Try It!
Aanvullende informatie
Lees onze blog over - Introductie van API-documentatie: Verbeter je API-ervaring