OpenAPI nel generatore di API dati

Annotazioni

La funzionalità Generatore API dati 2.0 descritta in questa sezione è attualmente in anteprima e potrebbe cambiare prima della disponibilità generale. Per altre informazioni, vedere Novità della versione 2.0.

La specifica OpenAPI è uno standard indipendente dal linguaggio per la documentazione delle API HTTP. Il generatore di API dati supporta OpenAPI per:

• Generazione di metadati per tutte le entità abilitate per REST definite nella configurazione di runtime
• Compilazione di tali metadati in uno schema OpenAPI valido
• Esposizione dello schema tramite un'interfaccia utente visiva (Swagger) o come file JSON serializzato
• Filtro dello schema per visualizzare solo i metodi e i campi HTTP accessibili per un determinato ruolo

Documento di descrizione OpenAPI

Il generatore di API dati genera un documento di descrizione OpenAPI usando la configurazione di runtime e i metadati del database per ogni entità abilitata per REST.

Lo schema viene compilato usando OpenAPI.NET SDK ed è conforme alla specifica OpenAPI v3.0.1. Viene restituito come documento JSON.

È possibile accedere al documento OpenAPI all'indirizzo:

GET /{rest-path}/openapi

Annotazioni

Per impostazione predefinita, il rest-path è api. Questo valore è configurabile. Per informazioni dettagliate, vedere Configurazione REST .

OpenAPI sensibile alle autorizzazioni

A partire da DAB 2.0, il documento OpenAPI riflette le autorizzazioni effettive configurate per ogni entità. Invece di documentare ogni possibile metodo HTTP, lo schema generato mostra solo i metodi e i campi a cui un determinato ruolo può accedere.

Modalità di mapping delle autorizzazioni ai metodi HTTP

DAB converte le autorizzazioni delle entità nella visibilità dei metodi HTTP nel documento OpenAPI:

Azione di autorizzazione	Metodi HTTP visualizzati
read	GET
create	POST
create + update	PUT, PATCH
delete	DELETE

Ad esempio, se il ruolo ha solo l'autorizzazione read sull'entità Book, il documento OpenAPI per il ruolo anonimo mostra solo le operazioni GET per /api/Book. Le POSToperazioni , PUTPATCH, e DELETE vengono omesse interamente.

Filtro a livello di campo

Quando le autorizzazioni includono regole a livello di campo include o exclude, lo schema OpenAPI riflette tali vincoli. Solo i campi accessibili al ruolo vengono visualizzati negli schemi di richiesta e risposta. Questo filtro offre ai consumer un'immagine accurata di ciò che l'API accetta e restituisce per il proprio ruolo.

Percorsi OpenAPI specifici per ruolo

DAB fornisce endpoint OpenAPI specifici del ruolo in modo da poter esaminare lo schema per qualsiasi ruolo configurato:

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

Il percorso di base /openapi restituisce la visualizzazione anonima predefinita. Ogni percorso specifico del ruolo restituisce uno schema filtrato in base alle autorizzazioni del ruolo.

Importante

I percorsi OpenAPI specifici del ruolo (/openapi/{role}) sono disponibili solo in modalità di sviluppo. In modalità di produzione, questi endpoint sono disabilitati per impedire l'enumerazione dei ruoli. Solo il percorso di base /openapi è disponibile in modalità produzione.

Annotazioni

Un endpoint specifico del ruolo restituisce 404 Not Found se il ruolo non dispone di autorizzazioni di entità configurate in qualsiasi punto della configurazione di runtime. Solo i ruoli con almeno una permissions voce in almeno un'entità producono un documento OpenAPI.

Esempio

Prendere in considerazione questa configurazione delle autorizzazioni:

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

Con questa configurazione:

• /api/openapi/anonymous mostra solo GET /api/Book con i campi iddi risposta , titlee year.
• /api/openapi/authenticated mostra GET, POST, PUT, PATCH, e DELETE su /api/Book con tutti i campi.

Interfaccia utente di Swagger

L'interfaccia utente di Swagger offre una visualizzazione interattiva basata sul Web dell'API basata sullo schema OpenAPI.

In modalità Development, Data API builder espone Swagger UI all'indirizzo:

GET /swagger

Questo endpoint non è annidato in rest-path per evitare conflitti con le entità definite dall'utente.