So validieren Sie OpenAPI-Dateien effektiv mit dem WSO2 API Manager

Die OpenAPI-Spezifikation (OAS) ist ein wesentlicher Aspekt des API-First-Designs. Daher ist es entscheidend, genaue und qualitativ hochwertige OpenAPI-Dateien zu pflegen, um eine nachhaltige API-Entwicklungspraxis zu gewährleisten. In diesem Artikel besprechen wir verschiedene Aspekte der OpenAPI-Datei-Validierung und die Werkzeuge, die dafür verwendet werden können. Wir konzentrieren uns hauptsächlich auf den WSO2 API Manager 4.2.0, der jetzt eine integrierte Methode zur Validierung von OpenAPI-Dateien bietet, ohne dass externe Werkzeuge benötigt werden. Zusätzlich zu den Standard-OAS-Regeln besprechen wir auch, wie Sie Ihre eigenen Validierungsregeln schreiben können, um Ihre OpenAPI-Dateien zu validieren und sicherzustellen, dass Ihre API-Definitionen den Standards und Richtlinien Ihrer Organisation entsprechen. Am Ende behandeln wir einige typische OpenAPI-Validierungsanforderungen mit einigen Beispiel-angepassten Regeln. Ich glaube, dieser Artikel wird einige wertvolle Ergänzungen zu Ihren API-Entwicklungspraktiken hinzufügen.

Bedeutung der OpenAPI-Spezifikation (OAS) im API-First-Design

Die OpenAPI-Spezifikation (OAS) ist ein Beschreibungsformat für REST-APIs und Webhooks. Es war früher als Swagger bekannt. Es ermöglicht uns, ganze APIs zu beschreiben, einschließlich verfügbarer Endpunkte/Operationen, Eingabe-/Ausgabeparameter, Authentifizierungsmethoden und so weiter. Daher ist es bei der Verwendung von OAS in der API-Entwicklung entscheidend, die Genauigkeit und Qualität der OpenAPI-Dateien zu gewährleisten, da der gesamte Lebenszyklus der API-Entwicklung davon abhängt. Es sollte also eine gute und einfache Möglichkeit geben, diese OpenAPI-Dateien zu validieren.

Schritte zur Validierung von Open API-Dateien

Bei der OAS-Validierung gibt es zwei Aspekte, die validiert werden sollen:

1. Open API-Dateien müssen gegen die Standard-OAS-Regeln validiert werden.
2. Open API-Dateien können auch gegen benutzerdefinierte Regeln validiert werden, zum Beispiel gegen unternehmensspezifische Regeln.

Standard-OAS-Regeln: Sicherstellung der Präzision in Open API-Dateien

Dies ist ein wichtiger Schritt, um sicherzustellen, dass Open API-Dateien genau sind, bewährte Praktiken befolgen und den etablierten OAS-Standards entsprechen. Es gibt Werkzeuge, um OpenAPI-Dateien gegen die OpenAPI-Spezifikation zu validieren. Spectral und Swagger-Editor sind zwei solche populären Werkzeuge.

Hier sind einige wichtige OAS-Regeln, die typischerweise unter dieser Kategorie validiert werden:

• Syntaxvalidierung des Dateiformats
  • Sicherstellen, dass die Open API-Datei das korrekte JSON/YAML-Format hat und keine Syntaxfehler aufweist.
• Schema-Validierung
  • Überprüfung der Korrektheit der Schemata-Strukturen
  • Datentypen und Objekteigenschaften sind innerhalb der OpenAPI-Spezifikation deklariert.
• Parameter-Validierung
  • Sicherstellen, dass Abfrageparameter, Pfadparameter, Header und Cookies korrekt mit Datentypen, Beschreibungen und Validierungen definiert sind.
• Ambiguous API resources
  • Ensure there are no conflicting API resources, for example, `/pets/{name}` and `/pets/{id}`.
• Mehrdeutige API-Ressourcen
  • Sicherstellen, dass keine widersprüchlichen API-Ressourcen vorhanden sind, z.B. /pets/{name} und /pets/{id}.
• Sicherheitsdefinitionen
  • Sicherstellen, dass jede API-Ressource mindestens eine erfolgreiche Antwort (2xx oder 3xx) hat.
• Versionierung und Kompatibilität
  • Sicherstellen, dass die API-Definition einer bestimmten Version der OpenAPI-Spezifikation entspricht und die Rückwärts- oder Vorwärtskompatibilität gewahrt bleibt.
• Fehlerbehandlung
  • Validierung der Fehlerantworten, Statuscodes und Fehlermeldungsstrukturen, die innerhalb der API-Spezifikation definiert sind.
• API-Beispiele
  • Sicherstellen, dass die angegebenen API-Anfrage-/Antwort-Payload-Beispiele gemäß der API-Definition gültig sind.

Bis Sie Ihre OpenAPI-Dateien gegen all diese Standardregeln validiert und fehlerfrei gemacht haben, sind sie keine echten OpenAPI-Dateien, sondern nur Textdateien. Durch die Verwendung eines OpenAPI-Validierungstools zur Validierung dieser Standardregeln können Sie Inkonsistenzen in den frühen Phasen des API-Entwicklungszyklus erkennen und sie zu tatsächlichen und genauen OpenAPI-Dateien machen, bevor Sie diese zur Erstellung echter APIs verwenden.

Konsistenz schaffen: Benutzerdefinierte Linter-Regeln für die Open API-Validierung

Organisationen und Entwicklungsteams haben in der Regel zusätzlich zu den Branchenstandards eigene Standards. Das gilt auch für APIs. Wenn eine Organisation APIs veröffentlichen möchte, möchte sie möglicherweise sicherstellen, dass API-Entwickler bestimmte Regeln einhalten, die auf den internen Standards und Richtlinien der Organisation basieren. Zum Beispiel Benennungsrichtlinien für API-Pfade und -Parameter, Verfügbarkeit von API-Beispielen, bestimmte Einschränkungen für API-Informationen usw. Um solche Anforderungen zu erleichtern, können benutzerdefinierte Linter-Regeln verwendet werden, um OpenAPI-Dateien zu validieren. Allerdings unterstützen nicht alle OpenAPI-Validierungstools benutzerdefinierte Linter-Regeln. Spectral ist eines dieser großartigen Tools, das sowohl Standard-OAS-Regeln als auch benutzerdefinierte Linter-Regeln unterstützt.

Nutzung des WSO2 API Managers für Open API-Dateien

Wenn Sie Benutzer des WSO2 API Managers sind, haben Sie das Glück, die volle Funktionalität des Spectral-Linter-Tools innerhalb des WSO2 API Managers zu haben, und Sie müssen sich nicht mehr darum kümmern, ein externes Tool nur zur Validierung von OpenAPI-Dateien zu verwenden. Seit Version 4.2.0 ist Spectral in den WSO2 API Manager mit zusätzlicher UI-Unterstützung integriert.

Wenn Sie jetzt eine OpenAPI-Datei in den WSO2 API Manager importieren, wird die Datei standardmäßig gegen die Standard-OAS-Regeln validiert und zeigt Ihnen eine Zusammenfassung der Fehler, Warnungen, Informationen und Hinweise an, wie unten gezeigt.

Sie können den Abschnitt Linter-Ergebnisse erweitern und weitere Details zu jedem Fehler/Warnung usw. lesen.

An diesem Punkt haben Sie zwei Optionen:

1. Die ursprüngliche OpenAPI-Datei aktualisieren und erneut importieren, um die API zu erstellen.
2. Fortfahren, um die API mit der aktuellen OpenAPI-Datei zu erstellen und die API später zu ändern, um die Fehler zu beheben.

Option 2 könnte eine geeignete Wahl sein, wenn Sie aus irgendeinem Grund die ursprüngliche OpenAPI-Datei nicht aktualisieren können, zum Beispiel, wenn Sie nicht der Eigentümer davon sind. Andererseits unterbricht es Ihren API-Erstellungsfluss nicht. Es lässt Sie einfach damit fortfahren. Wenn Sie diese Option wählen, können Sie die Linter-Fehler nach dem Erstellen der API beheben. Dazu sollten Sie zum Abschnitt API-Definition gehen und dann die API-Definition Bearbeiten.

Wenn Sie dann zur „Linter“-Ansicht auf der rechten Seite wechseln, können Sie die von Spectral erkannten Fehler und Warnungen sehen. Wenn Sie Fehler/Warnungen im linken Bereich beheben, verschwindet die entsprechende Fehler-/Warnmeldung im rechten Bereich.

Sobald Sie mit dem Ergebnis zufrieden sind, können Sie die API-Definition speichern und mit dem Rest Ihres API-Lebenszyklus fortfahren.

Konfigurieren von benutzerdefinierten Linter-Regeln im WSO2 API Manager

Wie bereits erwähnt, ist eine der leistungsfähigsten Funktionen von Spectral die Möglichkeit, benutzerdefinierte Regeln zu definieren. Das können Sie auch im WSO2 API Manager tun. Er bietet Ihnen zusätzliche Benutzeroberflächen, um diesen Prozess reibungslos zu gestalten. So fügen Sie eine neue benutzerdefinierte Regel hinzu:

1. Gehen Sie zum Admin-Portal. Klicken Sie im linken Bereich unter Einstellungen auf Erweitert. Dann werden Sie zum Editor für „Erweiterte Konfigurationen“ weitergeleitet.

2. Hier müssen Sie einen neuen Schlüssel „LinterCustomRules“ zu dieser Konfigurationsdatei hinzufügen. (Die Standardkonfiguration hat keinen Abschnitt „LinterCustomRules“.) Innerhalb des Abschnitts „LinterCustomRules“ fügen Sie einen neuen Schlüssel „rules“ hinzu, wie im untenstehenden Bild gezeigt.

3. Innerhalb dieses Abschnitts können Sie beliebig viele benutzerdefinierte Regeln mit benutzerdefinierten Regel-Schlüsseln definieren. Hier ist eine Beispielregel, die validiert, ob die Kontakt-E-Mail der API eine Yenlo-E-Mail ist. (Wir werden diese Regel im nächsten Abschnitt weiter besprechen.)

4. Nachdem Sie die oben genannte Regel gespeichert haben, sehen Sie, wenn neue Fehler durch die neue Regel identifiziert werden, diese im Abschnitt API-Definition des Publisher-Portals wie folgt.

Erkundung fortgeschrittener benutzerdefinierter Linter-Regeln für die Open API-Validierung

Eine benutzerdefinierte Linter-Regel hat mehrere Teile. Schauen wir uns an, was jeder von ihnen bedeutet:

• Beschreibung: Dies beschreibt die Regel.
• Given: Dies spezifiziert, welcher Teil der OpenAPI-Datei validiert werden soll.
• Then: Dies spezifiziert, wie es validiert werden soll. In diesem Abschnitt können wir angeben, was mit welcher Funktion validiert werden soll. Wir können hier auch mehr Funktionsoptionen angeben.
• Schweregrad: Dies kann einer der folgenden Werte sein: Fehler, Warnung, Info, Hinweis und Aus. Dies gibt die Schwere des Fehlers an.
• Nachricht: Dies ist eine optionale Nachricht, die mit den erkannten Fehlern angezeigt werden soll.

Sie können mehr über diese Optionen in der offiziellen Spectral-Dokumentation lesen.

Illustrierende Beispiele benutzerdefinierter Regeln für die Open API-Validierung

Schauen wir uns nun einige benutzerdefinierte Regeln an, die im typischen API-Entwicklungsprozess nützlich sein können.

1. Beginnen wir mit dem bereits erwähnten E-Mail-Beispiel:

"company-info-email-rule": {
    "description": "Contact email address must be a Yenlo email.",
    "given": "$",
    "severity": "error",
    "then": {
        "field": "info.contact.email",
        "function": "pattern",
        "functionOptions": {
            "match": "^[a-z]+@yenlo.com$"
        }
    }
 }

Diese Regel definiert, dass die Kontakt-E-Mail des Info-Abschnitts dem Regex  `^[a-z]+@yenlo.com$` entsprechen muss, was bedeutet, dass es eine Yenlo-E-Mail sein muss. Hier wird die „pattern“-Funktion mit der „match“-Option verwendet.

2. Alle POST-API-Ressourcen sollten ein Beispiel für eine Anfrage haben:

"post-request-example": {
    "description": "All POST application/json requests must have examples.",
    "given": "$.paths.*.post.requestBody.content.application/json",
    "severity": "error",
    "then": {
        "field": "examples",
        "function": "truthy"
    }
 }

Diese Regel definiert, dass, wenn es POST-Anfragekörper mit dem Inhaltstyp application/json gibt, diese ein definiertes Beispiel haben sollten. Hier bedeutet die Funktion „truthy“, dass etwas (in diesem Fall das Feld „examples“) existieren muss. Die gegenteilige Funktion davon ist die „falsy“-Funktion, die sicherstellt, dass etwas nicht existiert.

3. Alle Schemaeigenschaften müssen im camelCase sein:

"model-properties-camelcase": {
    "description": "All schema properties must be in camelCase.",
    "given": "$.components.schemas.*.*.~",
    "severity": "warn",
    "then": {
        "function": "casing",
        "functionOptions": {
           "type": "camel"
        }
    }
 }

Diese Regel verwendet die „casing“-Funktion mit ihrer Option „type“. Spectral unterstützt die folgenden „cases“ von Haus aus:

• camel (z.B.: veryLongName)
• pascal (z.B.: VeryLongName)
• kebab (z.B.: very-long-name)
• cobol (z.B.: VERY-LONG-NAME)
• snake (z.B.: very_long_name)
• macro (z.B.: VERY_LONG_NAME)

4. Alle Tags müssen in alphabetischer Reihenfolge sortiert sein:

"openapi-tags-alphabetical": {
    "description": "OpenAPI objects should have tags in the alphabetical order.",
    "given": "$",
    "severity": "warnn",
    "then": {
        "field": "tags",
        "function": "alphabetical",
        "functionOptions": {
           "keyedBy": "name"
        }
    }
 }

Hier verwendet die Regel die „alphabetical“-Funktion, die sicherstellt, dass gegebene Array-Elemente oder Objekteigenschaften in alphabetischer Reihenfolge nach einem durch die Option „keyedBy“ angegebenen Schlüssel sortiert sind.

5. Tags sollten nur aus einer vordefinierten Liste stammen:

"whitelisted-tags": {
    "description": "Tags should be coming from the given list of tags.",
    "given": "$.paths.*",
    "severity": "error",
    "then": {
        "field": "tags",
        "function": "enumeration",
        "functionOptions": {
            "values": [
                "users",
                "articles",
                "categories"
            ]
        }
    }
 }

Diese Regel verwendet die „enumeration“-Funktion, die verwendet werden kann, um einen Wert auf eine der angegebenen Werte zu beschränken.

6. Alle Operationen müssen mindestens 1 Tag, aber nicht mehr als 3 haben:

"operation-singular-tag": {
    "description": "Operations must have between 1 and 3 types.",
    "given": "$.paths.*",
    "severity": "error",
    "then": {
        "field": "tags",
        "function": "length",
        "functionOptions": {
            "max": 3,
            "min": 1
        }
    }
 }

Diese Regel verwendet die „length“-Funktion, die Min- und Max-Optionen hat.

Ähnlich können Sie komplexere benutzerdefinierte Regeln mit verschiedenen Spectral-Kernfunktionen definieren. Weitere Informationen dazu finden Sie hier.

Aufbau einer nachhaltigen API-Entwicklungspraxis

In diesem Artikel haben wir besprochen, was die OpenAPI-Spezifikation ist und warum wir sie brauchen. Wir haben die beiden Aspekte der OpenAPI-Validierung und die Unterstützung durch Werkzeuge besprochen. Insbesondere haben wir über Spectral gesprochen, das jetzt in den WSO2 API Manager integriert ist, und wie Sie es verwenden können, um Ihre OpenAPI-Dateien sowohl gegen Standard-OAS-Regeln als auch gegen benutzerdefinierte Linter-Regeln zu validieren. Wir haben uns ausführlicher mit benutzerdefinierten Regeln befasst und einige typische Validierungsanwendungsfälle mit Beispiel-angepassten Regeln behandelt. Wenn Sie also ein API-Entwickler, ein API-Produktbesitzer oder jemand sind, der im Bereich der API-Entwicklung arbeitet, glaube ich, dass das, was wir in diesem Artikel besprochen haben, für Sie nützlich sein könnte, um eine nachhaltige API-Entwicklungspraxis in Ihrer Organisation aufrechtzuerhalten.