OpenAPI in de Data API Builder

Opmerking

De data-API builder 2.0-functionaliteit die in deze sectie wordt beschreven, is momenteel in preview en kan veranderen vóór algemene beschikbaarheid. Zie Wat is er nieuw in versie 2.0 voor meer informatie.

De OpenAPI-specificatie is een taalagnostische standaard voor het documenteren van HTTP-API's. Data API Builder ondersteunt OpenAPI door:

• Metagegevens genereren voor alle REST-entiteiten die zijn gedefinieerd in de runtimeconfiguratie
• Deze metagegevens compileren in een geldig OpenAPI-schema
• Het schema weergeven via een visuele ui (Swagger) of als een geserialiseerd JSON-bestand
• Het schema filteren om alleen HTTP-methoden en -velden weer te geven die toegankelijk zijn voor een bepaalde rol

OpenAPI-beschrijvingsdocument

Data API Builder genereert een OpenAPI-beschrijvingsdocument met behulp van de runtimeconfiguratie en de databasemetagegevens voor elke entiteit met REST-functionaliteit.

Het schema wordt gebouwd met behulp van de OpenAPI.NET SDK en voldoet aan de OpenAPI-specificatie v3.0.1. Het wordt uitgevoerd als een JSON-document.

U kunt het OpenAPI-document openen op:

GET /{rest-path}/openapi

Opmerking

Standaard is de rest-pathapi. Deze waarde kan worden geconfigureerd. Zie DE REST-configuratie voor meer informatie.

Machtigingsbewuste OpenAPI

Vanaf DAB 2.0 weerspiegelt het OpenAPI-document de werkelijke machtigingen die voor elke entiteit zijn geconfigureerd. In plaats van elke mogelijke HTTP-methode te documenteren, toont het gegenereerde schema alleen de methoden en velden waartoe een bepaalde rol toegang heeft.

Hoe machtigingen worden gekoppeld aan HTTP-methoden

DAB vertaalt entiteitsmachtigingen in zichtbaarheid van HTTP-methoden in het OpenAPI-document:

Machtigingsactie	Getoonde HTTP-methoden
read	GET
create	POST
create + update	PUT, PATCH
delete	DELETE

Als de anonymous rol bijvoorbeeld alleen read machtigingen voor de Book entiteit heeft, worden in het OpenAPI-document voor de anonieme rol alleen GET bewerkingen voor /api/Bookweergegeven. De POST, PUT, PATCH en DELETE bewerkingen worden volledig weggelaten.

Filteren op veldniveau

Wanneer machtigingen veldniveau include of exclude regels bevatten, weerspiegelt het OpenAPI-schema deze beperkingen. Alleen velden die toegankelijk zijn voor de rol, worden weergegeven in de aanvraag- en antwoordschema's. Deze filtering geeft gebruikers een nauwkeurig beeld van wat de API accepteert en retourneert voor hun rol.

Rolspecifieke OpenAPI-paden

DAB biedt rolspecifieke OpenAPI-eindpunten, zodat u het schema voor elke geconfigureerde rol kunt inspecteren:

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

Het basispad /openapi retourneert de standaard anonieme weergave. Elk rolspecifiek pad retourneert een schema dat is gefilterd op de machtigingen van die rol.

Belangrijk

Rolspecifieke OpenAPI-paden (/openapi/{role}) zijn alleen beschikbaar in de ontwikkelingsmodus. In de productiemodus zijn deze eindpunten uitgeschakeld om de opsomming van rollen te voorkomen. Alleen het basispad /openapi is beschikbaar in de productiemodus.

Opmerking

Een rolspecifiek eindpunt retourneert 404 Not Found als de rol geen entiteitsmachtigingen heeft die ergens in de runtimeconfiguratie zijn geconfigureerd. Alleen rollen met ten minste één permissions vermelding op ten minste één entiteit genereren een OpenAPI-document.

Voorbeeld

Overweeg deze machtigingsconfiguratie:

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

Met deze configuratie:

• /api/openapi/anonymous wordt alleen GET /api/Book weergegeven met antwoordvelden id, titleen year.
• /api/openapi/authenticatedtoont GET, POST, PUT, en PATCHDELETE bewerkingen op /api/Book met alle velden.

Swagger UI

Swagger UI biedt een interactieve webweergave van de API op basis van het OpenAPI-schema.

In Development de modus maakt Data API Builder Swagger UI beschikbaar op:

GET /swagger

Dit eindpunt is niet genest onder de rest-path om conflicten met door de gebruiker gedefinieerde entiteiten te voorkomen.