OpenAPI no construtor de API de Dados

Observação

A funcionalidade do Construtor de API de Dados 2.0 descrita nesta seção está atualmente em versão prévia e pode ser alterada antes da disponibilidade geral. Para obter mais informações, consulte o que há de novo na versão 2.0.

A especificação OpenAPI é um padrão independente de idioma para documentar APIs HTTP. O Construtor de API de Dados dá suporte ao OpenAPI por:

• Gerando metadados para todas as entidades habilitadas para REST definidas na configuração de runtime
• Compilando esses metadados em um esquema OpenAPI válido
• Expondo o esquema por meio de uma interface do usuário visual (Swagger) ou como um arquivo JSON serializado
• Filtrando o esquema para mostrar apenas métodos HTTP e campos acessíveis para uma determinada função

Documento de descrição do OpenAPI

O Construtor de API de Dados gera um documento de descrição OpenAPI usando a configuração de runtime e os metadados de banco de dados para cada entidade habilitada para REST.

O esquema é criado usando o SDK do OpenAPI.NET e está em conformidade com a Especificação do OpenAPI v3.0.1. É gerado como um documento JSON.

Você pode acessar o documento OpenAPI em:

GET /{rest-path}/openapi

Observação

Por predefinição, o rest-path é api. Esse valor é configurável. Consulte a configuração REST para obter detalhes.

OpenAPI sensível a permissões

A partir do DAB 2.0, o documento OpenAPI reflete as permissões reais configuradas para cada entidade. Em vez de documentar todos os métodos HTTP possíveis, o esquema gerado mostra apenas os métodos e campos que uma determinada função pode acessar.

Como as permissões são mapeadas para métodos HTTP

O DAB converte permissões de entidade na visibilidade do método HTTP no documento OpenAPI:

Ação de permissão	Métodos HTTP mostrados
read	GET
create	POST
create + update	PUT, PATCH
delete	DELETE

Por exemplo, se a função anonymous tiver apenas permissão read sobre a entidade Book, o documento OpenAPI para a função anônima mostrará apenas operações GET para /api/Book. As POSToperações , PUT, PATCHe DELETE são totalmente omitidas.

Filtragem no nível do campo

Quando as permissões incluem regras de campo ou em nível de campo, o esquema OpenAPI reflete essas restrições. Somente os campos acessíveis à função aparecem nos esquemas de solicitação e resposta. Essa filtragem fornece aos consumidores uma imagem precisa do que a API aceita e retorna para sua função.

Caminhos OpenAPI específicos para funções

O DAB fornece endpoints OpenAPI específicos para cada função, permitindo que você inspecione o esquema para qualquer função configurada.

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

O caminho base /openapi retorna a exibição anônima padrão. Cada caminho específico para a função retorna um esquema filtrado para as permissões daquela função.

Importante

Os caminhos OpenAPI específicos à função (/openapi/{role}) estão disponíveis apenas no modo de desenvolvimento. No modo de produção, esses pontos de extremidade são desabilitados para impedir a enumeração de funções. Somente o caminho base /openapi está disponível no modo de produção.

Observação

Um ponto de extremidade específico da função retornará 404 Not Found se a função não tiver permissões de entidade configuradas em qualquer lugar na configuração de runtime. Somente as funções que têm pelo menos uma permissions entrada em pelo menos uma entidade geram um documento OpenAPI.

Exemplo

Considere esta configuração de permissão:

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

Com esta configuração:

• /api/openapi/anonymous mostra apenas GET /api/Book com campos idde resposta, titlee year.
• /api/openapi/authenticated mostra as operações de GET, POST, PUT, PATCH e DELETE em /api/Book com todos os campos.

Interface do usuário do Swagger

Swagger UI fornece uma visão interativa da API baseada no esquema OpenAPI.

No modo Development, o Data API builder expõe o Swagger UI em:

GET /swagger

Esse endpoint não está aninhado sob o rest-path para evitar conflitos com entidades definidas pelo usuário.