OpenAPI в построителе API данных

Замечание

Функции построителя данных 2.0, описанные в этом разделе, находятся в предварительной версии и могут измениться до общедоступной доступности. Дополнительные сведения см. в статье "Новые возможности" версии 2.0.

Спецификация OpenAPI — это стандарт, не зависящий от языка для документирования API HTTP. Конструктор API для данных поддерживает OpenAPI путем:

  • Создание метаданных для всех сущностей с поддержкой REST, определенных в конфигурации среды выполнения.
  • Компиляция метаданных в допустимую схему OpenAPI
  • Предоставление схемы через визуальный пользовательский интерфейс (Swagger) или в виде сериализованного JSON-файла
  • Фильтрация схемы для отображения только методов и полей HTTP, доступных для данной роли

Документ описания OpenAPI

Построитель API данных создает документ описания OpenAPI с помощью конфигурации среды выполнения и метаданных базы данных для каждой сущности с поддержкой REST.

Схема создается с помощью пакета SDK OpenAPI.NET и соответствует спецификации OpenAPI версии 3.0.1. Это выводится в виде документа JSON.

Вы можете получить доступ к документу OpenAPI по адресу:

GET /{rest-path}/openapi

Замечание

По умолчанию rest-path имеет значение api. Это значение можно настроить. Дополнительные сведения см. в конфигурации REST .

OpenAPI с поддержкой разрешений

Начиная с DAB 2.0, документ OpenAPI отражает фактические разрешения, настроенные для каждой сущности. Вместо того чтобы документировать все возможные методы HTTP, созданная схема показывает только методы и поля, к которым может получить доступ данная роль.

Сопоставление разрешений с методами HTTP

DAB преобразует разрешения сущности в видимость метода HTTP в документе OpenAPI:

Действие разрешения Показаны методы HTTP
read GET
create POST
create + update PUT, PATCH
delete DELETE

Например, если anonymous роль имеет разрешение только read к сущности Book, документ OpenAPI для анонимной роли отображает только GET операции для /api/Book. Операции POST, PUT, PATCH и DELETE полностью опущены.

Фильтрация на уровне поля

Если разрешения включают правила уровня include поля или exclude, схема OpenAPI отражает эти ограничения. В схемах запроса и ответа отображаются только поля, доступные роли. Эта фильтрация дает потребителям точное представление о том, что API принимает и возвращает в соответствии с их ролью.

Пути OpenAPI для конкретной роли

DAB предоставляет конечные точки OpenAPI для ролей, чтобы проверить схему для любой настроенной роли:

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

/openapi Базовый путь возвращает анонимное представление по умолчанию. Каждый путь для конкретной роли возвращает схему, отфильтрованную по разрешениям этой роли.

Это важно

Пути OpenAPI для ролей (/openapi/{role}) доступны только в режиме разработки. В рабочем режиме эти конечные точки отключены, чтобы предотвратить перечисление ролей. Только базовый /openapi путь доступен в режиме рабочей среды.

Замечание

Конечная точка для конкретной роли возвращает 404 Not Found, если у роли нигде в конфигурации среды выполнения не настроены разрешения на сущности. Только роли, имеющие по крайней мере одну permissions запись на одной сущности, создают документ OpenAPI.

Пример

Рассмотрим эту конфигурацию разрешений:

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

С этой конфигурацией:

  • /api/openapi/anonymous показывает только GET /api/Book с полями ответа id, title и year.
  • /api/openapi/authenticated показывает GET, POST, PUT, PATCH и DELETE операции на /api/Book со всеми полями.

Пользовательский интерфейс Swagger

Пользовательский интерфейс Swagger предоставляет интерактивное веб-представление API на основе схемы OpenAPI.

В режиме Development построитель API данных предоставляет пользовательский интерфейс Swagger по адресу:

GET /swagger

Эта конечная точка не вложена в rest-path, чтобы избежать конфликтов с определяемыми пользователем сущностями.

  • Last updated on