Problemen met API-import oplossen

Dit artikel is een geconsolideerde referentie voor elke fout, waarschuwing en onverwacht gedrag die is gedocumenteerd in de API-documentatiefunctie van Document360. Gebruik het om problemen met imports, authenticatie, de Try It!-functie, rendering en de knowledge base-site te diagnosticeren en op te lossen.

Importfouten

Ongeldig formaat – API-bestandsupload mislukt

Wanneer het gebeurt: Wanneer één of meer antwoorden in je OpenAPI-specificatiebestand het vereiste content gedeelte missen.

Waarom het gebeurt: Document360 handhaaft strikte OpenAPI-validatieregels. Hoewel een bestand validatie kan doorstaan in tools zoals Swagger Editor, vereist Document360 dat alle antwoorden expliciet zowel het mediatype (bijvoorbeeld application/json) als een schemareferentie onder een content blok definiëren. Antwoorden die leeg zijn of direct naar een schema verwijzen zonder wrapper content zullen deze fout veroorzaken.

Hoe je het oplost:

1. Open je OpenAPI-specificatiebestand in een teksteditor of IDE.
2. Zoek alle responsdefinities die leeg zijn of die een schema zonder content blok verwijzen.
   Onjuist:

   responses:
     "200": {}

Correct:

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/YourSchema"

3. Sla het bestand op en upload het opnieuw naar Document360.
   Als het probleem blijft bestaan, neem dan contact op met het Document360-supportteam .

Ongeldige URL

Wanneer het gebeurt: Bij het maken van een API-referentie vanuit een URL kan de gegeven URL niet worden opgehaald of opgelost.

Waarom het gebeurt: De URL kan misvormd zijn, onbereikbaar zijn vanaf de servers van Document360, of wijzen op een bron die geen geldige OpenAPI-specificatie is.

Hoe je het oplost: Controleer of de URL correct wordt opgelost in een browser of met curl. Zorg ervoor dat het een geldig JSON- of YAML OpenAPI-document teruggeeft. Corrigeer de URL en probeer het opnieuw.

Niet-ondersteund bestandsformaat

Wanneer het gebeurt: Wanneer het geüploade bestand geen ondersteund formaat is.

Hoe je het oplost: Zorg ervoor dat je bestand een van de volgende is: JSON, YAML of YML. Document360 ondersteunt OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 en Postman Collections.

API-referentie kan niet toevoegen – ongeldig specificatiebestand

Foutmelding: "API-referentie kan niet worden toegevoegd. Deze operatie kan niet worden voltooid. Zorg ervoor dat u een geldig specificatiebestand heeft verstrekt."

Wanneer het gebeurt: Bij het uploaden van een YAML-specificatiebestand dat is gekopieerd of geëxporteerd uit een rich-text editor of tekstverwerker.

Waarom het gebeurt: Het geüploade YAML-bestand is misvormd en geen geldig OpenAPI 3.0 YAML-document. Dit gebeurt vaak wanneer het bestand is gekopieerd of geëxporteerd uit een rich-text editor, die opmaaktekens introduceert zoals \f0\fs24 of trailing backslashes die het YAML-formaat breken.

1. Valideer je specificatiebestand: Open je YAML-bestand in een tool zoals Swagger Editor of een code-editor om fouten of opmaakfouten te controleren.
2. Zoek naar ongewenste opmaaktekens: Controleer op tekens zoals \f0\fs24 of achteroverliggende schreeuwstrepen \ (vooral in de endpointbeschrijving) die mogelijk zijn toegevoegd tijdens copy-paste-uit een rijke tekstbron. Deze kunnen het YAML-formaat breken.
3. Maak het bestand schoon: Gebruik een gewone tekst- of code-editor om speciale opmaaktekens te verwijderen. Vermijd het gebruik van tekstverwerkers bij het bewerken of opslaan van YAML-bestanden.
4. Upload het bestand opnieuw: Nadat je het bestand hebt opgeschoond en hebt gecontroleerd of het een geldige OpenAPI 3.0 YAML is, probeer het opnieuw te uploaden.

Samenvatting en tags niet weergegeven na import

Wanneer het gebeurt: Na het importeren van een specificatie tonen endpoint-artikelen onjuiste titels of verschijnen ze onder onverwachte categorieënmappen.

Waarom het gebeurt: De en-velden tags worden gedefinieerd op padniveau in de spec in plaats van binnen het operatieobject (get, post, put, of delete).summary Daarnaast moet het tags veld altijd als een array worden geschreven, zelfs als slechts één tag wordt gebruikt.

Hoe je het oplost:

1. Open je OpenAPI-specificatiebestand in een teksteditor.
2. Verplaats de summary en-velden tags binnen elk bewerkingsobject en zorg ervoor dat tags het als een array wordt geschreven.
   Onjuist:

   /your-endpoint:
     summary: My Endpoint
     tags: My Category
     get:
       ...

Correct:

   /your-endpoint:
     get:
       summary: My Endpoint
       tags: ["My Category"]
       ...

3. Sla het bestand op en importeer het opnieuw in Document360. De geïmporteerde artikelen gebruiken de summary waarde als artikeltitel, en tag-gebaseerde mappen worden correct aangemaakt.
   Als het probleem blijft bestaan, neem dan contact op met het Document360-supportteam .

Upload mislukt met 400 Bad Request – specificatiebestand te groot

Wanneer het gebeurt: Bij het uploaden van een geldig YAML- of JSON OpenAPI-specificatiebestand dat eindpunten bevat met diep geneste responsschema's en meerdere responscodes per eindpunt.

Waarom het gebeurt: Hoewel het bestand geldig kan zijn als YAML en externe validators zoals Swagger Editor kan passeren, handhaaft Document360 een interne artikelgroottelimiet. Wanneer een eindpunt responsschema's bevat die acht of meer niveaus diep zijn genest over meerdere responscodes, overschrijdt de resulterende datagrootte deze limiet en kan niet worden verwerkt of opgeslagen.

Hoe je het oplost:

1. Open je OpenAPI-specificatiebestand in een teksteditor of IDE.
2. Voor elk eindpunt behoudt u slechts één 201-responstype, één 400-serie responstype en het standaardresponstype. Verwijder alle extra antwoordcodes.
3. Voor eindpunten waarbij alleen de 201-respons diep geneste schema's bevat, behoud alleen het 201-responstype en verwijder de 400-serie en standaardresponstypen volledig.
4. Sla het aangepaste bestand op en upload het opnieuw naar Document360.

i️ OPMERKING
Als publicatie mislukt na een succesvolle upload, neem dan contact op met het supportteam van Document360. Publiceren kan backend-ondersteuning vereisen vanwege de beperking van de artikelgrootte.

Top-level tagbeschrijvingen worden niet weergegeven in de API-documentatie

Wanneer het gebeurt: Beschrijvingen en metadata die zijn gedefinieerd in topniveau OpenAPI-tagobjecten worden niet weergegeven in de gegenereerde API-documentatie.

Waarom het gebeurt: Wanneer een OpenAPI-specificatiebestand topniveau-tags bevat die worden gebruikt om API-operaties te groeperen, zet Document360 die tags tijdens de import om in mapcategorieën. Mapcategorieën worden alleen gebruikt voor het organiseren van eindpunten en genereren geen zelfstandige contentpagina's. Daardoor wordt geen enkele beschrijving of metadata die binnen die topniveau-tagobjecten is gedefinieerd, gerenderd.

Oplossing: Voeg de relevante context direct toe aan de individuele endpointbeschrijvingen binnen de tag, zodat de informatie zichtbaar is op de gegenereerde endpointpagina's.

Nog steeds problemen?

Als bovenstaande stappen je probleem niet oplossen, neem dan rechtstreeks contact op met het Document360-supportteam .

FAQ