Veri API'si oluşturucusunda OpenAPI

Uyarı

Bu bölümde açıklanan Veri API oluşturucusu 2.0 işlevselliği şu anda önizleme aşamasındadır ve genel kullanılabilirlik öncesinde değişebilir. Daha fazla bilgi için bkz. Sürüm 2.0'daki yenilikler.

OpenAPI belirtimi, HTTP API'lerini belgelemede dil açısından bağımsız bir standarttır. Veri API'si oluşturucusu OpenAPI'i şu şekilde destekler:

  • Çalışma zamanı yapılandırmasında tanımlanan tüm REST özellikli varlıklar için meta veriler oluşturma
  • Bu meta verileri geçerli bir OpenAPI şemasına derleme
  • Şemayı görsel kullanıcı arabirimi (Swagger) aracılığıyla veya serileştirilmiş JSON dosyası olarak ortaya çıkarma
  • Şemayı yalnızca belirli bir rol için erişilebilen HTTP yöntemlerini ve alanlarını gösterecek şekilde filtreleme

OpenAPI açıklama belgesi

Veri API'si oluşturucusu, rest özellikli her varlık için çalışma zamanı yapılandırmasını ve veritabanı meta verilerini kullanarak bir OpenAPI açıklama belgesi oluşturur.

Şema , OpenAPI.NET SDK kullanılarak oluşturulur ve OpenAPI Belirtimi v3.0.1'e uygundur. JSON belgesi olarak çıktı olarak sunulur.

OpenAPI belgesine şu konumdan erişebilirsiniz:

GET /{rest-path}/openapi

Uyarı

Varsayılan olarak , rest-path şeklindedir api. Bu değer yapılandırılabilir. Ayrıntılar için bkz. REST yapılandırması .

İzin kullanan OpenAPI

DAB 2.0'dan başlayarak, OpenAPI belgesi her varlık için yapılandırılan gerçek izinleri yansıtır. Oluşturulan şema, mümkün olan her HTTP yöntemini belgeleme yerine yalnızca belirli bir rolün erişebileceği yöntemleri ve alanları gösterir.

İzinler HTTP yöntemleriyle nasıl haritalanır?

DAB, OpenAPI belgesindeki varlık izinlerini HTTP yöntemi görünürlüğüne çevirir:

İzin işlemi Gösterilen HTTP yöntemleri
read GET
create POST
create + update PUT, PATCH
delete DELETE

Örneğin, anonymous rolü Book varlık üzerinde yalnızca read iznine sahipse, anonim rol için OpenAPI belgesi /api/Book üzerinde yalnızca GET işlemleri gösterir. POST, PUT, PATCHve DELETE işlemleri tamamen atlanır.

Alan düzeyinde filtreleme

İzinler alan düzeyi include veya exclude kurallar içerdiğinde, OpenAPI şeması bu kısıtlamaları yansıtır. İstek ve yanıt şemalarında yalnızca rol tarafından erişilebilen alanlar görüntülenir. Bu filtreleme, tüketicilere API'nin rolleri için neleri kabul edip döndürdüğüne ilişkin doğru bir resim sağlar.

Rol-özgü OpenAPI yolları

DAB, yapılandırılmış herhangi bir rol için şemayı inceleyebilmeniz için role özgü OpenAPI uç noktaları sağlar:

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

Temel /openapi yol varsayılan anonim görünümü döndürür. Role özgü her yol, bu rolün izinlerine göre filtrelenmiş bir şema döndürür.

Önemli

Role özgü OpenAPI yolları (/openapi/{role}) yalnızca Geliştirme modunda kullanılabilir. Üretim modunda, rol numaralandırmasını önlemek için bu uç noktalar devre dışı bırakılır. Üretim modunda yalnızca temel /openapi yol kullanılabilir.

Uyarı

Role özgü bir uç noktası, rolün çalışma zamanı yapılandırmasının hiçbir yerinde yapılandırılmış varlık izinleri yoksa 404 Not Found döndürür. Yalnızca en az bir varlıkta en az bir permissions girişi bulunan roller OpenAPI belgesi oluşturur.

Example

Şu izin yapılandırmasını göz önünde bulundurun:

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

Bu yapılandırmayla:

  • /api/openapi/anonymous yalnızca GET /api/Book yanıt alanları id, titleve yearile gösterilir.
  • /api/openapi/authenticated GET, POST, PUT, PATCH ve DELETE işlemlerini /api/Book tüm alanlarıyla gösterir.

Swagger Kullanıcı Arabirimi

Swagger kullanıcı arabirimi , OpenAPI şemasına göre API'nin etkileşimli, web tabanlı bir görünümünü sağlar.

Modda Development , Veri API oluşturucusu Swagger kullanıcı arabirimini şu konumda kullanıma sunar:

GET /swagger

Bu uç nokta, kullanıcı tanımlı varlıklarla çakışmaları önlemek için rest-path öğesinin altında iç içe değildir.

  • Last updated on