Partager via

OpenAPI dans le générateur d’API de données

Note

La fonctionnalité 2.0 du Générateur d’API de données décrite dans cette section est actuellement en préversion et peut changer avant la disponibilité générale. Pour plus d’informations, consultez Nouveautés de la version 2.0.

La spécification OpenAPI est une norme indépendante du langage pour documenter les API HTTP. Le générateur d’API de données prend en charge OpenAPI par :

  • Génération de métadonnées pour toutes les entités compatibles REST définies dans la configuration du runtime
  • Compilation de ces métadonnées dans un schéma OpenAPI valide
  • Exposition du schéma via une interface utilisateur visuelle (Swagger) ou en tant que fichier JSON sérialisé
  • Filtrage du schéma pour afficher uniquement les méthodes ET champs HTTP accessibles pour un rôle donné

Document de description OpenAPI

Le générateur d’API de données génère un document de description OpenAPI à l’aide de la configuration du runtime et des métadonnées de base de données pour chaque entité REST.

Le schéma est généré à l’aide du Kit de développement logiciel (SDK) OpenAPI.NET et est conforme à la spécification OpenAPI v3.0.1. Le résultat est un document JSON.

Vous pouvez accéder au document OpenAPI à l’adresse suivante :

GET /{rest-path}/openapi

Note

Par défaut, le rest-path est api. Cette valeur est configurable. Pour plus d’informations, consultez la configuration REST .

OpenAPI prenant en compte les autorisations

À compter de DAB 2.0, le document OpenAPI reflète les autorisations réelles configurées pour chaque entité. Au lieu de documenter toutes les méthodes HTTP possibles, le schéma généré affiche uniquement les méthodes et les champs auxquels un rôle donné peut accéder.

Comment les autorisations correspondent aux méthodes HTTP

DAB convertit les autorisations d’entité en visibilité de méthode HTTP dans le document OpenAPI :

Action d’autorisation Méthodes HTTP affichées
read GET
create POST
create + update PUT, PATCH
delete DELETE

Par exemple, si le rôle a uniquement l’autorisation read sur l’entité Book, le document OpenAPI pour le rôle anonyme affiche les opérations GET uniquement pour /api/Book. Les opérations POST, PUT, PATCH et DELETE sont entièrement omises.

Filtrage au niveau du champ

Lorsque les autorisations incluent des règles au niveau du champ include ou exclude, le schéma OpenAPI reflète ces contraintes. Seuls les champs accessibles au rôle apparaissent dans les schémas de requête et de réponse. Ce filtrage donne aux utilisateurs une image précise de ce que l’API accepte et renvoie pour leur rôle.

Chemins OpenAPI spécifiques au rôle

DAB fournit des points de terminaison OpenAPI spécifiques au rôle afin de pouvoir inspecter le schéma pour n’importe quel rôle configuré :

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

Le chemin d’accès de base /openapi retourne la vue anonyme par défaut. Chaque chemin spécifique au rôle retourne un schéma filtré sur les autorisations de ce rôle.

Important

Les chemins OpenAPI spécifiques au rôle (/openapi/{role}) sont disponibles uniquement en mode développement. En mode production, ces points de terminaison sont désactivés pour empêcher l’énumération des rôles. Seul le chemin de base /openapi est disponible en mode Production.

Note

Un point de terminaison spécifique au rôle retourne 404 Not Found si le rôle n’a aucune autorisation d’entité configurée n’importe où dans la configuration du runtime. Seuls les rôles qui ont au moins une permissions entrée sur au moins une entité génèrent un document OpenAPI.

Exemple

Tenez compte de cette configuration d’autorisation :

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

Avec cette configuration :

  • /api/openapi/anonymous s’affiche uniquement GET /api/Book avec les champs idde réponse, titleet year.
  • /api/openapi/authenticated affiche GET, POST, PUT, PATCH et DELETE les opérations sur /api/Book avec tous les champs.

Interface utilisateur Swagger

L’interface utilisateur Swagger fournit une vue interactive basée sur le web de l’API basée sur le schéma OpenAPI.

En Development mode, le générateur d’API de données expose l’interface utilisateur Swagger à l’adresse suivante :

GET /swagger

Ce point de terminaison n’est pas imbriqué sous la rest-path section pour éviter les conflits avec les entités définies par l’utilisateur.

  • Last updated on