OpenAPI a Data API Builderben

Megjegyzés:

Az ebben a szakaszban ismertetett Data API Builder 2.0 funkció jelenleg előzetes verzióban érhető el, és az általános rendelkezésre állás előtt változhat. További információ: A 2.0-s verzió újdonságai.

Az OpenAPI specifikáció egy nyelvfüggetlen szabvány a HTTP API-k dokumentálására. A Data API Builder a következővel támogatja az OpenAPI-t:

  • Metaadatok létrehozása a futtatókörnyezet konfigurációjában definiált összes REST-kompatibilis entitáshoz
  • Metaadatok összeállítása érvényes OpenAPI-sémába
  • A séma megjelenítése vizuális felhasználói felületen (Swagger) vagy szerializált JSON-fájlként
  • A séma szűrése, hogy csak az adott szerepkörhöz elérhető HTTP-metódusok és mezők jelenjenek meg

OpenAPI leírási dokumentum

A Data API Builder egy OpenAPI-leíró dokumentumot hoz létre az egyes REST-kompatibilis entitások futtatókörnyezeti konfigurációjának és adatbázis-metaadatainak használatával.

A séma a OpenAPI.NET SDK használatával készült, és megfelel az OpenAPI 3.0.1-s specifikációjának. JSON-dokumentumként jelenik meg.

Az OpenAPI-dokumentum a következő címen érhető el:

GET /{rest-path}/openapi

Megjegyzés:

Alapértelmezés szerint a rest-path értéke api. Ez az érték konfigurálható. Részletekért lásd a REST-konfigurációt .

Engedélyérzékeny OpenAPI

A DAB 2.0-tól kezdve az OpenAPI-dokumentum az egyes entitásokhoz konfigurált tényleges engedélyeket tükrözi. Minden lehetséges HTTP-metódus dokumentálása helyett a létrehozott séma csak azokat a metódusokat és mezőket jeleníti meg, amelyekhez egy adott szerepkör hozzáfér.

A HTTP-metódusokhoz kapcsolódó engedélyek leképezése

A DAB az entitásengedélyeket HTTP-metódusok láthatóságára fordítja le az OpenAPI-dokumentumban:

Engedélyezési művelet Megjelenített HTTP-módszerek
read GET
create POST
create + update PUT, PATCH
delete DELETE

Ha például a anonymous szerepkör csak read engedéllyel rendelkezik az Book entitásra vonatkozóan, a névtelen szerepkörre vonatkozó OpenAPI-dokumentum csak a /api/Book bizonyos GET műveleteket jeleníti meg. A POST, PUT, PATCHés DELETE a műveletek teljes egészében ki vannak hagyva.

Mezőszintű szűrés

Ha az engedélyek mezőszintet include vagy exclude szabályokat tartalmaznak, az OpenAPI-séma ezeket a korlátozásokat tükrözi. A kérelem- és válaszsémákban csak a szerepkör számára elérhető mezők jelennek meg. Ez a szűrés pontos képet ad a felhasználóknak arról, hogy az API mit fogad el és mit ad vissza az ő szerepük szerint.

Szerepkörspecifikus OpenAPI-elérési utak

A DAB szerepkörspecifikus OpenAPI-végpontokat biztosít, így bármilyen konfigurált szerepkört megvizsgálhat a sémában:

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

Az alap /openapi elérési út az alapértelmezett névtelen nézetet adja vissza. Minden szerepkörspecifikus elérési út egy olyan sémát ad vissza, amely az adott szerepkör engedélyeinek szűrve van.

Fontos

A szerepkörspecifikus OpenAPI-útvonalak (/openapi/{role}) csak fejlesztési módban érhetők el. Éles módban ezek a végpontok le vannak tiltva a szerepkör-számbavétel megakadályozása érdekében. Éles módban csak az alap /openapi elérési út érhető el.

Megjegyzés:

A szerepkörspecifikus végpont akkor 404 Not Found ad vissza, ha a szerepkör nem rendelkezik a futtatókörnyezet konfigurációjában bárhol konfigurált entitásengedélyekkel. Csak azok a szerepkörök hoznak létre OpenAPI-dokumentumot, amelyek legalább egy permissions bejegyzéssel rendelkeznek legalább egy entitáson.

Example

Fontolja meg ezt az engedélykonfigurációt:

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

Ezzel a konfigurációval:

  • /api/openapi/anonymouscsak GET /api/Book válaszmezőkkel idés titleyear.
  • /api/openapi/authenticated megjeleníti a GET, POST, PUT, PATCH és DELETE műveleteket az /api/Book összes mezőjén.

Swagger felhasználói felület

A Swagger felhasználói felülete interaktív, webes nézetet biztosít az API-ról az OpenAPI-séma alapján.

Módban Development a Data API Builder a következő helyen teszi elérhetővé a Swagger felhasználói felületét:

GET /swagger

Ez a végpont nincs beágyazva a rest-path alá, hogy elkerüljük a felhasználó által definiált entitásokkal való ütközéseket.

  • Last updated on