OpenAPI v Tvůrci rozhraní Data API

Poznámka:

Funkce tvůrce rozhraní Data API 2.0 popsané v této části jsou aktuálně ve verzi Preview a můžou se změnit před obecnou dostupností. Další informace najdete v tématu Co je nového ve verzi 2.0.

Specifikace OpenAPI je jazykově nezávislý standard pro dokumentaci rozhraní HTTP API. Tvůrce rozhraní Data API podporuje OpenAPI podle:

  • Generování metadat pro všechny entity s podporou REST definované v konfiguraci modulu runtime
  • Kompilace metadat do platného schématu OpenAPI
  • Zveřejnění schématu prostřednictvím vizuálního uživatelského rozhraní (Swagger) nebo jako serializovaný soubor JSON
  • Filtrování schématu tak, aby zobrazovaly pouze metody HTTP a pole přístupná pro danou roli

Dokument popisu OpenAPI

Tvůrce rozhraní Data API generuje dokument s popisem OpenAPI pomocí konfigurace modulu runtime a metadat databáze pro každou entitu s podporou REST.

Schéma se sestaví pomocí sady OpenAPI.NET SDK a odpovídá specifikaci OpenAPI v3.0.1. Výstup je jako dokument JSON.

K dokumentu OpenAPI se dostanete na adrese:

GET /{rest-path}/openapi

Poznámka:

Ve výchozím nastavení je rest-pathapi. Tato hodnota je konfigurovatelná. Podrobnosti najdete v konfiguraci REST .

OpenAPI pracující s oprávněními

Od verze DAB 2.0 odráží dokument OpenAPI skutečná oprávnění nakonfigurovaná pro každou entitu. Místo zdokumentování každé možné metody HTTP se vygenerované schéma zobrazuje pouze metody a pole, ke kterým má daná role přístup.

Mapování oprávnění na metody HTTP

DAB překládá oprávnění entit do viditelnosti metody HTTP v dokumentu OpenAPI:

Povolení akce Zobrazené metody HTTP
read GET
create POST
create + update PUT, PATCH
delete DELETE

Pokud má například anonymous role oprávnění pouze read k entitě Book, dokument OpenAPI pro anonymní roli zobrazuje pouze operace GET pro /api/Book. Operace POST, PUT, PATCHa DELETE jsou zcela vynechány.

Filtrování na úrovni pole

Pokud oprávnění zahrnují pravidla na úrovni pole include nebo exclude, schéma OpenAPI odráží tato omezení. Ve schématech požadavků a odpovědí se zobrazí pouze pole přístupná pro tuto roli. Toto filtrování poskytuje uživatelům přesný přehled o tom, co rozhraní API přijímá a vrací pro svou roli.

Cesty OpenAPI specifické pro roli

DAB poskytuje koncové body OpenAPI specifické pro roli, abyste mohli zkontrolovat schéma pro libovolnou nakonfigurovanou roli:

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

Základní /openapi cesta vrátí výchozí anonymní zobrazení. Každá cesta specifická pro roli vrátí schéma filtrované podle oprávnění této role.

Důležité

Cesty OpenAPI specifické pro role (/openapi/{role}) jsou k dispozici pouze v režimu vývoje. V produkčním režimu jsou tyto koncové body zakázané, aby se zabránilo výčtu rolí. V produkčním režimu je k dispozici pouze základní /openapi cesta.

Poznámka:

Koncový bod specifický pro roli vrátí 404 Not Found , pokud tato role nemá žádná oprávnění entity nakonfigurovaná kdekoli v konfiguraci modulu runtime. OpenAPI dokument vygenerují pouze role, které mají alespoň jednu permissions položku na alespoň jedné entitě.

Příklad

Zvažte tuto konfiguraci oprávnění:

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

S touto konfigurací:

  • /api/openapi/anonymous zobrazuje pouze GET /api/Book s poli odpovědi id, title a year.
  • /api/openapi/authenticated zobrazuje GET, POST, PUT, PATCH, a DELETE operace na /api/Book se všemi poli.

Swagger UI

Swagger UI poskytuje interaktivní webové zobrazení rozhraní API založené na schématu OpenAPI.

Tvůrce rozhraní Data API zveřejňuje uživatelské rozhraní Swagger v režimu na adrese:

GET /swagger

Tento koncový bod není vnořený pod rest-path entitami, aby nedocházelo ke konfliktům s entitami definovanými uživatelem.

  • Last updated on