Zusätzliche Metadaten-Endpunktfunktionen

Alternative Optionen zum Rendern von Schemas

Ein Abfrageparameter ist ein Ausdruck, welcher der HTTP-Anforderung hinzugefügt wird und die Standardantwort ändert. Die /openapi.json-Endpunkte unterstützen die folgenden Abfrageparameter, die verwendet werden können, um die Art und Weise zu ändern, in der Schemametadaten gerendert werden.

• filterByUser: Legt fest, ob Endpunkte und Schemaeigenschaften durch die Autorisierung dieses Benutzers gefiltert werden.
  • Standardmäßig auf „false“ festgelegt
• prettyPrint: Gibt an, ob das zurückgegebene Schema „hübsch gedruckt“ werden soll, so dass es größer, aber lesbarer wird.
  • Standardmäßig auf „false“ festgelegt

Verwenden Sie die folgende Syntax, um einer HTTP-Anforderung Abfrageparameter hinzuzufügen:

?<parameterName>=<value>

Um einer HTTP-Anforderung zusätzliche Abfrageparameter hinzuzufügen, verwenden Sie für jeden Abfrageparameter nach dem ersten die folgende Syntax:

&<parameterName>=<value>

Die folgende HTTP-Anforderung ruft beispielsweise die Metadaten für die Common API ab. Sie aktiviert auch filterByUser und prettyPrint.

http://localhost:8080/cc/rest/common/v1/openapi.json?filterByUser=true&prettyPrint=true

Konvertieren von Schema-Metadaten in SDKs

Einige Tools wie openapi-generator bieten die Möglichkeit, ein Swagger-Schema zu verwenden und ein Software Development Kit (SDK) auszugeben. Die /openapi.json-Endpunkte unterstützen den folgenden Abfrageparameter, der verwendet werden kann, um die Art und Weise zu ändern, wie ein SDK gerendert wird.

• enablePolymorphism: Legt fest, ob das Diskriminator-/oneOf-Muster zur Ausgabe von Schemas verwendet wird, wenn das gültige Set von Feldern basierend auf bestimmten Attributen der Daten, z. B. dem Land oder Untertyp, variieren kann.
  • Standardmäßig auf „true“ festgelegt
  • Wenn dieser Parameter auf „false“ gesetzt ist, enthält das Schema in diesen Fällen die Obermenge aller gültigen Felder. Beispielsweise enthalten Adressenschemas alle Felder für alle Länder und keine separaten Schemas für verschiedene Länder.
  • Wenn Sie diesen Parameter auf „false“ setzen, kann die Schemaausgabe für Tools, die diesen Teil des OpenAPI-Schemas nicht unterstützen, möglicherweise besser nutzbar werden.

Verwenden Sie die folgende Syntax, um einer HTTP-Anforderung Abfrageparameter hinzuzufügen:

?<parameterName>=<value>

Die folgende HTTP-Anforderung ruft beispielsweise die Metadaten für die Common API ab. Sie deaktiviert außerdem den Polymorphismus.

http://localhost:8080/cc/rest/common/v1/openapi.json?enablePolymorphism=false

(Weitere Informationen zu openapi-generator finden Sie unter https://github.com/OpenAPITools/openapi-generator/.)

Abfragen mit Typenschlüsselfiltern

Einige Typenlisten weisen eine hierarchische Beziehung auf. Diese Typenlisten verwenden Typenschlüsselfilter. Ein Typenschlüsselfilter ist eine Zuordnung, die für einen Typencode in einer Typenliste die gültigen Werte in einer zugehörigen Typenliste identifiziert. Weitere Informationen zu Typenschlüsselfiltern finden Sie im Anwendungshandbuch.

In den folgenden Typenlisten werden beispielsweise Typenschlüsselfilter verwendet:

• ActivityType: Der allgemeine Typ der Aktivität, z. B. „General“, „Approval“ oder „Assignment Review“.
• ActivityCategory: Die spezifische Kategorie einer Aktivität, z. B. „Interview“, „Reminder“ oder „Approval Denied“.

Wenn der ActivityType einer Aktivität auf „General“ gesetzt ist, sind einige ActivityCategory-Werte (z. B. „Interview“ und „Reminder“) gültig, andere (z. B. „Approval Denied“) nicht.

Wenn die Typenliste mit einem Typenschlüsselfilter verknüpft ist, können Sie bei Verwendung des /typelists/{typelistName}-Endpunkts die Antwort auf nur die Typencodes beschränken, die gültig sind, wenn die übergeordnete Typenliste auf einen bestimmten Typencode gesetzt ist. Die Syntax sieht folgendermaßen aus:

/typelists/{typelistName}?typekeyFilter=category:cn:relatedTypelist.Typecode

Wobei gilt:

• relatedTypelist ist der Name der zugehörigen Typenliste.
• Typecode ist der Typencode, der als Filter verwendet wird

Dieser Aufruf ruft beispielsweise alle Typencodes in der Typenliste ActivityCategory ab:

GET /common/v1/typelists/ActivityCategory

Dieser Aufruf ruft jedoch nur die Typencodes in der ActivityCategory-Typenliste ab, die gültig sind, wenn ActivityType auf „General“ gesetzt ist:

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:cn:ActivityType.general

Einschließen zurückgezogener Typencodes

Standardmäßig gibt der common/v1/typelists/{typelistName}-Endpunkt nur nicht zurückgezogene Typencodes zurück. Sie können zurückgezogene Typencodes einschließen, indem Sie dem Aufruf den folgenden Abfrageparameter hinzufügen:

?includeRetired=true

Schritte des Lernprogramms

1. Starten Sie in Postman eine neue Anforderung, indem Sie auf das + rechts neben der Registerkarte Launchpad klicken.
2. Geben Sie als Basic Auth-Autorisierung den Benutzer su und das Kennwort gw an.
3. Geben Sie den folgenden Aufruf ein und klicken Sie dann auf Senden:
   • GET http://localhost:8080/cc/rest/common/v1/typelists/ClaimantType
4. Die Antwort-Nutzdaten enthalten alle nicht zurückgezogenen Anspruchstellertypen. Überprüfen Sie, ob die ersten drei Codes in den Nutzdaten wie folgt sind: insured, householdmember, veh_ins_driver.)
5. Ändern Sie den Aufruf, indem Sie am Ende den folgenden Abfrageparameter hinzufügen und dann auf Senden klicken:
   • ?typekeyFilter=category:cn:LossType.PR
6. Die Antwort-Nutzdaten enthalten jetzt nur Anspruchstellertypen, die für Sachschadenfälle relevant sind. Überprüfen Sie, ob die ersten drei Codes in den Nutzdaten jetzt wie folgt sind: insured, householdmember, propertyowner. (veh_ins_driver wird nicht mehr angezeigt, weil es sich nicht um einen gültigen Anspruchstyp für einen Sachschadenfall handelt.)