Dit artikel behandelt alles wat je nodig hebt om je API-referenties in Document360 te beheren. Nieuwe referenties aanmaken, deze synchroon houden met je specificatie, en de beschikbare acties gebruiken om je API-documentatie te bekijken, bewerken, publiceren en organiseren.
API-referentielijst
De API-referentielijst geeft je een centraal overzicht van alle geconfigureerde API-referenties in je werkruimte. Om erbij te komen, navigeer je naar API-documentatie ({ }) in de linker navigatiebalk en klik je op API-referenties in het linker navigatiepaneel.
Vanaf hier kun je de naam, het type en de laatst bijgewerkte datum van elke referentie zien. Je kunt ook een nieuwe API-referentie aanmaken door rechtsboven op Nieuwe API te klikken.
Maak een nieuwe API-referentie aan
Om een nieuwe API-referentie aan te maken, klik je op het keuzemenu Aanmaken in de bovenste navigatiebalk en selecteer je Nieuwe API. Dit opent het referentievenster Nieuwe API, waar je vier opties hebt:
- API-definitie uploaden - Upload een JSON-, YAML- of YML-specificatiebestand direct vanaf je apparaat of vanaf de Document360-schijf.
- Maak aan vanaf URL - Haal automatisch je specificatie op van een gehoste URL.
- CI/CD Flow - Integreer met je pipeline om documentatie automatisch bij te werken bij elke specificatiewijziging. Vereist Node.js.
- Probeer het voorbeeld van de Pet Store API-bestand - Gebruik het voorbeeldspecificatiebestand van Document360 om de werkruimte te verkennen voordat je je eigen bestand uploadt.
Document360 ondersteunt OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 en Postman API-specificaties. Binnen elke API-werkruimte kun je maximaal 3 API-referenties aanmaken.
Definitie van de upload-API
- Selecteer de radioknop Upload API definitie.
- Klik op Uploaden vanaf mijn apparaat om te uploaden vanuit je lokale opslag, of Kies uit Drive om een bestand van Document360 Drive te selecteren. Je kunt je bestand ook direct in het venster slepen en neerzetten.
- Document360 parseert het bestand en genereert de API-referentie. Als waarschuwingen worden gedetecteerd, verbreed dan het gedeelte Waarschuwingen en Waarschuwingen om ze te bekijken.
- Klik op de Nieuwe API-referentie om door te gaan naar het publicatiebevestigingsvenster.
Maak aan vanaf URL
- Selecteer de knop 'Aanmaken vanaf URL' en klik op Volgende.
- Voer de URL in die naar je OpenAPI-specificatiebestand verwijst.
- Klik op Nieuwe API-referentie. Document360 haalt de specificatie op en verwerkt ze.
CI/CD-stroom
De CI/CD-flow laat je je API-documentatie automatisch synchroon houden met je specificatie. In plaats van elke keer handmatig een nieuwe specificatie te uploaden wanneer je API verandert, integreer je de Document360 CLI in je pipeline, zodat documentatie automatisch wordt bijgewerkt bij elke specificatiewijziging.
Voor volledige installatie-instructies, zie het artikel over CI/CD-integratie .
API-referentieacties
Zodra een API-referentie is aangemaakt, klik je op het More (⋯) icoon ernaast in de API-referentielijst om toegang te krijgen tot de volgende acties:
| Actie | Wat het doet |
|---|---|
| Bewerking | Werk het specificatiebestand of de URL bij waaruit de referentie is gemaakt. |
| Resync | Genereer de documentatie opnieuw vanuit de nieuwste versie van de specificatie op de bestaande URL. |
| Bekijk de API-definitie | Bekijk de preview van het ruwe API-specificatiebestand. |
| Download de originele API-bron | Download de huidige versie van het specificatiebestand naar je lokale opslag. |
| Publiceren | Publiceer alle conceptartikelen in de API-referentie naar de Knowledge Base-site. |
| Verwijderen | Verwijder de API-referentie en alle gegenereerde inhoud permanent. |
| Bekijk logs | Bekijk waarschuwingen, waarschuwingen en fouten van de meest recente import of resync. |
Om lezers toe te staan het API-bronbestand van de Knowledge Base-site te downloaden, zorg ervoor dat de schakelaar ' Download download API'-code is ingeschakeld in de instellingen van het Knowledge Base-portaal.
Je documentatie synchroon houden
Wanneer je API verandert - nieuwe endpoints toegevoegd, parameters bijgewerkt, antwoorden aangepast, maar je hoeft je documentatie niet handmatig bij te werken. Het regenereren van je API-referentie haalt automatisch alle wijzigingen uit je specificatie binnen.
Alle aangepaste inhoud die je aan individuele endpoint-artikelen hebt toegevoegd, blijft behouden wanneer je je documentatie opnieuw genereert. Alleen de door specificaties gegenereerde content wordt bijgewerkt.
Resync vanaf een bestaande URL
- Klik in de API-referentielijst op het Meer (⋯) icoon naast de referentie die je wilt bijwerken.
- Klik op Resync. De documentatie wordt opnieuw gegenereerd vanuit de nieuwste versie van de specificatie op de bestaande URL.
Bijwerken naar een nieuwe URL
- Klik op het Meer (⋯) icoon naast de referentie.
- Klik op Bewerken.
- Voer de nieuwe URL in het URL-veld .
- Klik op Update.
Regenereer vanuit een spec-bestand
- Klik op het Meer (⋯) icoon naast de referentie.
- Klik op Bewerken.
- Upload het nieuwste specificatiebestand in JSON-, YAML- of YML-formaat.
- Klik op Update.
Resync via CI/CD
Als je API-referentie is ingesteld met de CI/CD-flow, gebeurt resyncing automatisch als onderdeel van je pipeline telkens wanneer je specificatie verandert. Je kunt ook een handmatige hersynchronisatie activeren met het apidocs:resync commando:
d360 apidocs:resync \
--apiKey=YOUR_API_KEY \
--userId=YOUR_USER_ID \
--apiReferenceId=YOUR_API_REFERENCE_ID \
--path=PATH_TO_SPEC_FILE
Voor volledige details over het opzetten en beheren van de CI/CD-stroom, zie het artikel over CI/CD-integratie .
Automatisch versus handmatig resync
| Creatiemethode | Automatische resync | Handmatig resync |
|---|---|---|
| Bestandsupload | Niet beschikbaar | Ja, via Edit in het portaal |
| URL-import | Niet beschikbaar | Ja, via Resync of Edit in het portaal |
| CI/CD-stroom | Ja - draait als onderdeel van je pijplijn | Ja, voer het CLI-commando handmatig uit |
Als je je API-documentatie hebt gegenereerd uit een URL of bestand, wordt deze niet automatisch bijgewerkt. Om de documentatie automatisch te laten updaten, integreer dan met de CI/CD-flow.
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 specificatiebestand veilig bij te werken:
- Upload het bijgewerkte specificatiebestand in het referentievenster Edit API .
- Als eindpunten worden verwijderd, wordt er een waarschuwing weergegeven. Klik op Verwijderde eindpunten tonen om de lijst van getroffen eindpunten te bekijken.
- Selecteer het vakje 'Bevestigen om door te gaan ' om de verwijdering te bevestigen.
- 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.
Als je het resync API-endpoint programmatisch gebruikt, stuur ForceImport = false dan de lijst met endpoints die verwijderd worden zonder doorgang te bekijken naar preview. Stuur ForceImport = true om te bevestigen en ga door.
Documentatie in concept bewaren
Na het uploaden of opnieuw synchroniseren van een specificatie kun je de resulterende documentatie in conceptmodus houden in plaats van deze direct te publiceren.
- Klik in het publicatiebevestigingsvenster op Sluiten in plaats van Publiceren. Alle gegenereerde artikelen blijven in conceptmodus.
- Conceptartikelen zijn zichtbaar in het Categorieën & Artikelen-paneel van het portaal, maar zijn niet toegankelijk voor lezers op de Knowledge Base-site.
- Je kunt vooraf ontwerpartikelen beoordelen, bewerken en aangepaste inhoud toevoegen aan conceptartikelen.
Geneste categorieën
Document360 ondersteunt tot drie niveaus van subcategorieën in de API-documentatieruimte. Categorieën worden aangemaakt op basis van de tagdefinities in je spec-bestand.
Om geneste categorieën te maken, gebruik je het > symbool in je OpenAPI-tags:
tags:
- name: "Pets > Details"
Dit creëert een Pets categorie met een Details subcategorie erin. Deze structuur blijft behouden tijdens de resync.
Als je spec meer dan drie nestingniveaus definieert, worden alle categorieën boven het derde niveau op het derde niveau geplaatst.
Categorieordening
De volgorde waarin categorieën in je documentatie verschijnen, komt overeen met de tagvolgorde die in je specificatiebestand is gedefinieerd. Om de categorievolgorde te wijzigen, herschik je de tags array in je specificatie en synchroniseer je opnieuw.
Categorie-opties
Door met de rechtermuisknop op een categorie te klikken in het paneel Categorieën & Artikelen, krijg je de volgende opties:
| Optie | Wat het doet |
|---|---|
| Hernoeming | Geef de categorie een nieuwe naam. |
| Artikel | Voeg een nieuw artikel of subartikel toe binnen de categorie. |
| Subcategorie | Voeg een subcategorie toe binnen de categorie. |
| Wijzigingstype | Verander het type categorie. |
| Set drive map | Koppel de categorie aan een Document360 Drive-map. |
| API-referentie bewerken | Werk het specificatiebestand of de URL bij voor de API-referentie. |
| Download de originele API-bron | Download het huidige specificatiebestand. |
| Publiceren | Publiceer alle conceptartikelen in de categorie. |
| Beveiliging | Configureer wie toegang heeft tot de categorie via het portaal en de kennisbanksite. |
Je kunt endpoint-artikelen tussen submappen binnen dezelfde API-referentiemap verplaatsen. Het is niet mogelijk om een endpoint-artikel van één API-referentiemap naar een andere API-referentiemap te verplaatsen.
FAQ
Hoe vaak wordt een API-referentie automatisch opnieuw gesynchroniseerd?
API-referenties die zijn gemaakt van een URL of bestand worden niet automatisch opnieuw gesynchroniseerd. Ze moeten handmatig via het portaal worden bijgewerkt. Om automatische updates mogelijk te maken, integreer je met de CI/CD-flow.
Kan ik een specifiek API-endpointartikel van de ene API-referentiemap naar de andere verplaatsen?
Nee. Je kunt endpoint-artikelen tussen submappen binnen dezelfde API-referentiemap verplaatsen, maar niet tussen verschillende API-referentiemappen.
Kan een API-documentatie dezelfde URL hebben als een kennisbasisartikel?
Nee. API-documentatieartikelen en kennisbasisartikelen kunnen niet dezelfde URL delen. Ze kunnen echter onder hetzelfde subdomein bestaan.
Kan ik gegenereerde documentatie in conceptmodus houden?
Ja. Na het uploaden van een specificatie, klik je op Sluiten in plaats van Publiceren in het bevestigingsvenster. Alle gegenereerde artikelen worden opgeslagen in conceptmodus.
Hoeveel niveaus van categorieën worden ondersteund?
De API-documentatiewerkruimte ondersteunt tot drie niveaus van subcategorieën. Extra niveaus worden neergestort naar het derde niveau.
Kan ik automatisch geneste mappen aanmaken vanuit het specificatiebestand?
Ja, met het > symbool in OpenAPI-tags (bijv. Pets > Details). Dit creëert een hiërarchische structuur die behouden blijft tijdens de resync.
Kunnen lezers tijdens de stilstand van het Document360-portaal toegang krijgen tot de Knowledge Base-site?
Ja. GET-aanroepen van de Customer API draaien onafhankelijk van het Document360-portaal, zodat lezers de site kunnen blijven gebruiken tijdens geplande onderhouds- of portaaluitval.