API-Spezifikationen in werden validiert API-Einblicke

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 3 Minuten Lesedauer

    • Sie können auf API-Spezifikationsvalidierungsregeln zugreifen, um sicherzustellen, dass Ihre API-Spezifikationen vollständig, konsistent und Best Practices entsprechen.

    Validierungsregeln identifizieren strukturelle Probleme frühzeitig während des Imports oder der Analyse, wodurch die API-Qualität insgesamt verbessert wird. Sie können diese Regeln verwalten, um die Standardisierung über API-Spezifikationen hinweg zu erzwingen und Fehler zu reduzieren, indem Sie nach fehlenden oder falschen Feldern suchen, bevor APIs in der Produktion veröffentlicht oder verwendet werden.

    API-Spezifikationen werden gespeichert

    Die Tabelle „API-Spezifikation“ [sn_api_Insights_WS_api_Specification] speichert die Spezifikationsdokumente, die einzelne APIs beschreiben. Jeder Datensatz enthält die folgenden Details, um die API zu identifizieren, zu der die Spezifikation gehört, und um mehrere Versionen zu verwalten.
    Tabelle : 1. API-Spezifikationsdetails
    Feld Beschreibung
    Name Name der API.
    Version Version der API.
    Typ Format und Version des verwendeten API-Spezifikationsstandards. Beispiel: Openapi3.0.0 Für eine OpenAPI-Spezifikation.
    Status Aktueller Status, der angibt, ob die API-Spezifikation anhand der geltenden Regeln und des Validierungsergebnisses validiert wurde. Gültige Werte sind:
    • Unverarbeitet : Gibt an, dass die API-Spezifikation nicht validiert wurde.
    • Gültig : Gibt an, dass die API-Spezifikation validiert und erfolgreich oder mit Warnungen verarbeitet wurde. Wenn Warnungen vorhanden sind, werden Details in angezeigt Nachricht Feld.
    • Ungültig : Gibt an, dass die API-Spezifikation validiert wurde, aber Fehler enthält. Fehlerdetails werden in angezeigt Nachricht Feld.
    Spezifikation Vollständiger Inhalt der API-Spezifikationsdatei.
    Hinweis:
    Enthält für OpenAPI das vollständige OpenAPI-Dokument, das Endpunkte, Methoden und Schema beschreibt.
    Nachricht Nachrichten werden generiert, nachdem alle Validierungsregeln für den Spezifikationstyp verarbeitet wurden. Sie enthalten Fehler oder Warnungen mit Erklärungen.

    Validierungsregelstruktur

    Die Tabelle „Spezifikationsvalidierungsregel“ [sn_api_Insights_WS_spec_validation_rule] speichert Validierungsregeln für die API-Spezifikationen, die in der Tabelle „API-Spezifikation“ [sn_api_Insights_WS_api_Specification] definiert sind.
    Hinweis:
    Die Rolle „sn_cmdb_Editor“ ist erforderlich, um Validierungsregeln zu bearbeiten oder zu löschen, und die Rolle „cmdb_read“, um sie anzuzeigen.

    Jede Validierungsregel enthält die folgenden Schlüsselkomponenten:

    Tabelle : 2. Validierungsregelkomponenten
    Komponente Beschreibung
    Spezifikation API-Spezifikation, für die die Regel entworfen wird.
    Version Version der API-Spezifikation, die die Regel validiert. Wenn angegeben, gilt die Regel nur für diese Versionen. Um die Validierung auf bestimmte Versionen zu beschränken, geben Sie sie im an Version Feld. Trennen Sie mehrere Werte durch Kommas. Beispiel: 1,0,1,1,2,0 .
    Hinweis:
    Wenn Version Feld ist leer, die Regel wird für alle installierten Versionen des angegebenen API-Spezifikationstyps ausgeführt.
    Typ Typ der auszuführenden Validierung. Die gültigen Werte sind:
    • Pfad : Überprüft, ob die spezifischen Schlüssel in Arrays von Objekten, einzelnen Objekten oder beidem in den angegebenen Abschnitten des API-Spezifikationsdokuments vorhanden sind.
    • Erwarteter Wert : Validiert, ob der angegebene Schlüssel mit den in angegebenen erwarteten Werten übereinstimmt Wert Feld. Diese Validierung gilt nur für einen einzelnen Schlüssel, der in angegeben ist Schlüssel Feld.
    Schlüssel Teil der zu verifizierenden Spezifikation. Wenn kein erwarteter Wert angegeben wird, können Sie mehrere Schlüssel in eingeben Schlüssel Feld, durch Kommas getrennt.
    Wert Erwartete Werte für den in angegebenen Schlüssel Schlüssel Feld. Trennen Sie mehrere Werte durch Kommas.
    Schweregrad Schweregrad des Validierungsregelergebnisses, entweder eine Warnung oder ein Fehler.
    Hinweis:
    Wenn auf „Warnung“ festgelegt, bleibt die API-Spezifikation gültig, wenn die Regel nicht erfüllt ist, was darauf hinweist, dass es sich nicht um einen Fehler handelt, und nur eine Meldung angezeigt wird.
    Nachricht Erklärung des Problems, wenn die Regel ausgelöst wird.
    Aktiv Option zum Aktivieren der Regel. Nur aktive Regeln werden von ausgelöst API Specification ValidationGeplante Aufgabe.

    API-Spezifikationsvalidierungsprozess

    Die API Specification ValidationDie geplante Aufgabe validiert automatisch unverarbeitete API-Spezifikationen anhand aktiver Regeln basierend auf ihrem Spezifikationstyp, um die Compliance mit den erforderlichen Standards sicherzustellen.

    Der Validierungsprozess umfasst:
    1. Alle aktiven Validierungsregeln werden aus der Tabelle „Spezifikationsvalidierungsregel“ [sn_api_Insights_WS_spec_validation_rule] abgerufen.
    2. APIs auswählen, die in der Tabelle „API-Spezifikation“ [sn_api_Insights_WS_api_Specification] als unverarbeitet markiert sind.
    3. Anwendung relevanter Validierungsregeln auf jede ausgewählte API basierend auf ihrem Spezifikationstyp, z. B. OpenAPI.
    4. Verifiziert das Vorhandensein oder die Richtigkeit bestimmter Felder oder ihrer Werte innerhalb der API-Spezifikation.
    5. Der Verarbeitungsstatus wird aktualisiert und Fehler oder Warnungen erfasst.

    Vordefinierte Regeln für OpenAPI-Spezifikationen

    Standardmäßig enthält die Anwendung die folgenden Validierungsregeln für OpenAPI-Spezifikationen:
    Tags validieren
    Überprüft, ob jedes Tag in der API-Spezifikation einen enthält Name Feld. Wenn Name Feld fehlt, das System gibt eine Warnmeldung zurück, markiert die Spezifikation jedoch als gültig.
    Validieren Sie die erforderlichen Abschnitte
    Überprüft, ob die API-Spezifikation die erforderlichen Abschnitte der obersten Ebene enthält: Info , Pfade , Und Komponenten . Wenn einer dieser Abschnitte fehlt, gibt das System eine Fehlermeldung zurück und markiert die Spezifikation als ungültig.
    Abschnitt „Server validieren“
    Überprüft, ob die API-Spezifikation einen enthält Server Abschnitt, der die Serverendpunkte definiert. Wenn Server Abschnitt fehlt. Das System gibt eine Fehlermeldung zurück und markiert die Spezifikation als ungültig.

    Diese vordefinierten Regeln verifizieren kritische Abschnitte wie Tagging, Metadaten und Serverdefinitionen in OpenAPI-Spezifikationen.