OpenAPI im Daten-API-Generator

Hinweis

Die in diesem Abschnitt beschriebene Funktionalität des Daten-API-Generators 2.0 befindet sich derzeit in der Vorschau und kann sich vor der allgemeinen Verfügbarkeit ändern. Weitere Informationen finden Sie unter Neuigkeiten in Version 2.0.

Die OpenAPI-Spezifikation ist ein sprachunabhängiger Standard für das Dokumentieren von HTTP-APIs. Der Daten-API-Generator unterstützt OpenAPI durch:

• Generieren von Metadaten für alle REST-fähigen Entitäten, die in der Laufzeitkonfiguration definiert sind
• Kompilieren dieser Metadaten in ein gültiges OpenAPI-Schema
• Verfügbarmachen des Schemas über eine visuelle UI (Swagger) oder als serialisierte JSON-Datei
• Filtern des Schemas, um nur HTTP-Methoden und Felder anzuzeigen, auf die für eine bestimmte Rolle zugegriffen werden kann

OpenAPI-Beschreibungsdokument

Der Daten-API-Generator generiert ein OpenAPI-Beschreibungsdokument mit der Laufzeitkonfiguration und den Datenbankmetadaten für jede REST-fähige Entität.

Das Schema wird mit dem OpenAPI.NET SDK erstellt und entspricht der OpenAPI Specification v3.0.1. Es wird als JSON-Dokument ausgegeben.

Sie können auf das OpenAPI-Dokument zugreifen unter:

GET /{rest-path}/openapi

Hinweis

Standardmäßig ist rest-pathapi. Dieser Wert kann konfiguriert werden. Details finden Sie in der REST-Konfiguration .

Berechtigungsbewusste OpenAPI

Ab DAB 2.0 spiegelt das OpenAPI-Dokument die tatsächlichen Berechtigungen wider, die für jede Entität konfiguriert sind. Anstatt jede mögliche HTTP-Methode zu dokumentieren, zeigt das generierte Schema nur die Methoden und Felder an, auf die eine bestimmte Rolle zugreifen kann.

Zuordnung von Berechtigungen zu HTTP-Methoden

DAB übersetzt Entitätsberechtigungen in die Sichtbarkeit der HTTP-Methode im OpenAPI-Dokument:

Berechtigungsvorgang	GEZEIGTe HTTP-Methoden
read	GET
create	POST
create + update	PUT, PATCH
delete	DELETE

Wenn die anonymous Rolle beispielsweise nur read Berechtigung für die Book Entität hat, zeigt das OpenAPI-Dokument für die anonyme Rolle nur GET Operationen für /api/Book. Die POST, PUT, PATCH und DELETE-Vorgänge werden vollständig weggelassen.

Filterung auf Feldebene

Wenn Berechtigungen die Regeln auf Feldebene include oder exclude enthalten, bezieht das OpenAPI-Schema diese Einschränkungen ein. Nur Felder, auf die die Rolle zugreifen kann, werden in den Anforderungs- und Antwortschemas angezeigt. Mit dieser Filterung erhalten Verbraucher ein genaues Bild davon, was die API für ihre Rolle akzeptiert und zurückgibt.

Rollenspezifische OpenAPI-Pfade

DAB stellt rollenspezifische OpenAPI-Endpunkte bereit, damit Sie das Schema für jede konfigurierte Rolle überprüfen können:

GET /{rest-path}/openapi
GET /{rest-path}/openapi/anonymous
GET /{rest-path}/openapi/authenticated
GET /{rest-path}/openapi/admin

Der Basispfad /openapi gibt die anonyme Standardansicht zurück. Jeder rollenspezifische Pfad gibt ein Schema zurück, das auf die Berechtigungen dieser Rolle gefiltert ist.

Von Bedeutung

Rollenspezifische OpenAPI-Pfade (/openapi/{role}) sind nur im Entwicklungsmodus verfügbar. Im Produktionsmodus sind diese Endpunkte deaktiviert, um die Rollenaufzählung zu verhindern. Nur der Basispfad /openapi ist im Produktionsmodus verfügbar.

Hinweis

Ein rollenspezifischer Endpunkt gibt zurück 404 Not Found , wenn die Rolle keine Entitätsberechtigungen hat, die an einer beliebigen Stelle in der Laufzeitkonfiguration konfiguriert sind. Nur Rollen mit mindestens einem permissions Eintrag für mindestens eine Entität generieren ein OpenAPI-Dokument.

Beispiel

Berücksichtigen Sie diese Berechtigungskonfiguration:

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": { "include": ["id", "title", "year"] }
            }
          ]
        },
        {
          "role": "authenticated",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    }
  }
}

Mit dieser Konfiguration:

• /api/openapi/anonymous zeigt nur GET /api/Book mit Antwortfeldern id, titleund year.
• /api/openapi/authenticated zeigt die GET, POST, PUT, PATCH und DELETE Vorgänge auf /api/Book mit allen Feldern.

Swagger-Benutzeroberfläche

Swagger UI stellt eine interaktive, webbasierte Ansicht der API basierend auf dem OpenAPI-Schema bereit.

Im Development Modus macht der Daten-API-Generator die Benutzeroberfläche von Swagger verfügbar unter:

GET /swagger

Dieser Endpunkt ist nicht unter rest-path geschachtelt, um Konflikte mit benutzerdefinierten Entitäten zu vermeiden.