API-Parameter haben oft komplexe Strukturen, wobei ein einzelner Endpunkt mehrere verschiedene Parameterkombinationen unterstützt. Zum Beispiel könnte ein Login-Endpunkt die Authentifizierung per Benutzername-Passwort, E-Mail-Passwort oder Telefonnummer-Verifizierungscodes unterstützen. Zahlungs-Endpunkte können verschiedene Methoden wie Kreditkarten, WeChat Pay oder Alipay anbieten, die jeweils unterschiedliche Felder erfordern.
Traditionelle Ansätze zur API-Dokumentation listen oft einfach alle möglichen Felder auf und verwenden Textbeschreibungen wie „Wählen Sie verschiedene Felder basierend auf verschiedenen Szenarien“. Dieser Ansatz ist weder präzise noch entwicklerfreundlich und führt oft zu Verwirrung. Apidog unterstützt die oneOf-, anyOf- und allOf-Funktionen von JSON Schema, wodurch Sie diese komplexen zusammengesetzten Datenstrukturen präzise in Ihrer API-Dokumentation beschreiben können.
Die drei Kombinationsmodi verstehen
In JSON Schema werden oneOf, anyOf und allOf verwendet, um mehrere Sub-Schemas zu kombinieren, aber sie haben unterschiedliche logische Bedeutungen:
- allOf: Kombiniert mehrere Regeln, wobei alle übereinstimmen müssen
- anyOf: Mindestens eine Ãœbereinstimmung ist erforderlich, mehrere Ãœbereinstimmungen sind akzeptabel
- oneOf: Muss genau einem Schema entsprechen; das Übereinstimmen mit null oder mehreren Schemas führt zu einem Fehler
Kombinationsmodi in Apidog einrichten
Apidog bietet zwei Möglichkeiten, diese Kombinationsmodi zu verwenden:
Ansatz des visuellen Editors
Die erste Methode verwendet das visuelle Bearbeitungspanel. Klicken Sie in Ihrem Projekt auf „Datenmodelle“, um ein neues Modell zu erstellen, und suchen Sie dann in der Typauswahl nach „Kombinationsmodi“. Wählen Sie den benötigten oneOf-, anyOf- oder allOf-Modus und definieren Sie dann spezifische Datenstrukturen für jedes Sub-Schema.
JSON-Schema-Code-Editor
Der zweite Ansatz beinhaltet die direkte Bearbeitung des JSON-Schema-Codes. Im Bearbeitungspanel für Datenmodelle können Sie in den Code-Modus wechseln und JSON Schema direkt schreiben, um diese logischen Kombinationsmuster zu definieren. Diese Methode ist direkter für Entwickler, die mit JSON Schema vertraut sind.
Anwendung dieser Muster in API-Endpunkten
Sobald Sie Ihre Datenmodelle definiert haben, können Sie diese in Ihrer API-Dokumentation verwenden. Wenn Sie Schnittstellen-Anfrageparameter bearbeiten, wählen Sie den Body-Typ als JSON. Im Bereich der Datenstruktur können Sie dann die soeben erstellten „Datenmodelle“ referenzieren oder direkt „Kombinationsmodi“ auswählen, um komplexe Parameterstrukturen zu definieren.
Dasselbe Prinzip gilt für die Definition von Antwortdaten. Beim Hinzufügen von Antwortbeispielen im Abschnitt „Rückgabeantwort“ können Sie Kombinationsmodi verwenden, um Antwortformate für verschiedene Szenarien zu beschreiben. Auf diese Weise können Entwickler klar verstehen, welche Datenstruktur in verschiedenen Situationen zurückgegeben wird.
Anwendungsfälle aus der Praxis
allOf: Mehrere Strukturen kombinieren
allOf kombiniert mehrere Strukturen miteinander – es geht nicht um Auswahl, sondern um Stapelung. allOf ändert die Feldhierarchie nicht; alle Felder landen im selben Objekt. Es stapelt einfach mehrere Regeln auf dieselben Daten. Stellen Sie es sich als „logisches UND“ vor – alle Substruktur-Einschränkungen müssen erfüllt sein.
Zum Beispiel dieses JSON Schema:
{
"allOf": [
{
"description": "Grundlegende Benutzerinformationen",
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
},
{
"description": "Kontaktinformationen",
"type": "object",
"properties": {
"email": { "type": "string", "format": "email" },
"phone": { "type": "string" }
},
"required": ["email"]
}
]
}
Dieses Schema bedeutet: Die finalen Daten müssen gleichzeitig sowohl die Struktur „grundlegende Benutzerinformationen“ als auch die Struktur „Kontaktinformationen“ erfüllen.
Mit anderen Worten, der Anfrage-Body muss id, name und email enthalten, während phone optional ist.
Gültige Daten:
{
"id": 1001,
"name": "John Doe",
"email": "john@example.com",
"phone": "1-800-000-0000"
}
Ungültige Daten:
{
"id": 1001,
"name": "John Doe"
}
Hier fehlt das erforderliche E-Mail-Feld und die zweite Struktur wird nicht erfüllt.
Dieser Ansatz eignet sich zum Aufteilen komplexer Objekte. Benutzerinformationen, Bestelldetails, Konfigurationselemente usw. können alle nach Funktionsmodulen in unabhängige Strukturen unterteilt und dann mit allOf kombiniert werden. Andere Schnittstellen, die Teile dieser Strukturen benötigen, können direkt darauf verweisen, ohne redundante Definitionen.
anyOf: Mindestens eine Bedingung erfüllen
anyOf listet mehrere mögliche Strukturen auf, und Daten gelten als gültig, solange sie mindestens einer davon entsprechen. Es ist irrelevant, ob mehrere Bedingungen erfüllt sind, und es erfordert keine eindeutige Übereinstimmung.
Zum Beispiel könnte ein Bezeichnerfeld eine E-Mail oder eine Telefonnummer sein. Diese beiden Formate sind deutlich unterschiedlich, gehören aber beide zur Kategorie der „Benutzer-Login-Anmeldeinformationen“.
Sie können anyOf verwenden, um diese „kann A oder B sein“-Absicht klar auszudrücken:
{
"type": "object",
"properties": {
"identifier": {
"description": "Benutzer-ID: kann E-Mail oder Telefonnummer sein",
"anyOf": [
{
"title": "E-Mail-Format",
"description": "Muss eine gültige E-Mail-Adresse sein",
"type": "string",
"format": "email"
},
{
"title": "Telefonformat",
"description": "Muss eine gültige internationale Telefonnummer sein",
"type": "string",
"pattern": "^\\+?[1-9]\\d{1,14}$"
}
]
},
"password": {
"type": "string",
"minLength": 6,
"description": "Login-Passwort, mindestens 6 Zeichen"
}
},
"required": ["identifier", "password"],
"description": "Anfrageparameter für Benutzer-Login"
}
Diese Struktur bedeutet: identifier ist ein String, der als gültig betrachtet wird, solange er entweder dem E-Mail-Format oder dem Telefonnummernformat entspricht.
Gültige Daten:
{
"identifier": "test@example.com",
"password": "123456"
}
{
"identifier": "+1-800-000-0000",
"password": "123456"
}
Ungültige Daten:
{
"identifier": "abc",
"password": "123456"
}
„abc“ ist weder eine E-Mail noch ein gültiges Telefonnummernformat und erfüllt keine der Bedingungen.
oneOf: Genau eine Option wählen
oneOf listet mehrere mögliche Strukturen auf, und Daten müssen genau einer davon entsprechen. Es betont die Exklusivität – Sie können nur eine wählen, nicht mehr, nicht weniger.
Zum Beispiel Zahlungsmethoden: Um eine Zahlung abzuschließen, müssen Benutzer eine von Kreditkarte, WeChat Pay oder Alipay wählen, können aber nicht zwei Methoden gleichzeitig verwenden, noch können sie keine wählen. Sie können diese „Einzelauswahl“-Logik mit oneOf definieren:
{
"properties": {
"paymentMethod": {
"description": "Zahlungsmethode, genau eine muss gewählt werden",
"oneOf": [
{
"title": "Kreditkartenzahlung",
"description": "Zahlung mit Kreditkarte, erfordert Kartennummer und Ablaufdatum",
"type": "object",
"properties": {
"type": { "const": "credit_card" },
"cardNumber": { "type": "string" },
"expiryDate": { "type": "string" }
},
"required": ["type", "cardNumber", "expiryDate"],
"additionalProperties": false
},
{
"title": "WeChat Pay",
"description": "Zahlung über WeChat, erfordert die OpenID des Benutzers",
"type": "object",
"properties": {
"type": { "const": "wechat" },
"openid": { "type": "string" }
},
"required": ["type", "openid"],
"additionalProperties": false
},
{
"title": "Alipay Zahlung",
"description": "Zahlung über Alipay, erfordert Konto-ID",
"type": "object",
"properties": {
"type": { "const": "alipay" },
"accountId": { "type": "string" }
},
"required": ["type", "accountId"],
"additionalProperties": false
}
]
}
}
}
Diese Definition bedeutet: paymentMethod ist ein Objekt, das nur einer der drei Substrukturen entsprechen kann.
Gültige Beispiele:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123456"
}
}
{
"paymentMethod": {
"type": "credit_card",
"cardNumber": "4111111111111111",
"expiryDate": "12/25"
}
}
Ungültiges Beispiel:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123",
"accountId": "2088102"
}
}
Auch wenn der Typ „wechat“ ist, könnte das Vorhandensein von accountId dazu führen, dass es mehreren Strukturen entspricht, was dazu führt, dass oneOf fehlschlägt. Das Hinzufügen von "additionalProperties": false verhindert diese Verwirrung (was bedeutet, dass keine zusätzlichen Felder erlaubt sind), um sicherzustellen, dass jede Struktur nur ihre eigenen definierten Felder zulässt. Apidog unterstützt die visuelle Konfiguration für additionalProperties.
Wenn Sie eine exklusive Wahl zwischen mehreren verschiedenen Typen treffen müssen, ist oneOf der direkteste und zuverlässigste Weg, dies auszudrücken.
Den richtigen Kombinationsmodus wählen
Die Wahl des Kombinationsmodus hängt hauptsächlich von Ihrer Geschäftslogik ab:
- Verwenden Sie allOf, wenn Sie mehrere Muster kombinieren und vererben müssen
- Verwenden Sie anyOf, wenn Sie flexible optionale Kombinationen benötigen
- Verwenden Sie oneOf, wenn Sie strikt exklusive Auswahlmöglichkeiten benötigen
Das Verständnis ihrer jeweiligen Rollen ermöglicht es Ihrer API-Dokumentation, komplexe Datenstrukturen präzise zu beschreiben, wodurch Schnittstellenbenutzer sofort klar verstehen, wie Parameter übergeben werden müssen.
Fazit
Die umfassende JSON-Schema-Unterstützung von Apidog ermöglicht es Entwicklern, präzise und klare API-Dokumentationen für selbst die komplexesten Parameterstrukturen zu erstellen. Durch die Nutzung von oneOf-, anyOf- und allOf-Kombinationen können Sie Unklarheiten beseitigen und API-Konsumenten eine kristallklare Anleitung bieten.
Bereit, die Leistungsfähigkeit fortschrittlicher API-Dokumentation zu erleben? Probieren Sie Apidog noch heute aus und sehen Sie, wie einfach es wird, komplexe API-Parameter präzise und klar zu verwalten.