OpenAPI di penyusun API Data

Nota

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Spesifikasi OpenAPI adalah standar bahasa-agnostik untuk mendokumen API HTTP. Penyusun API Data mendukung OpenAPI dengan:

  • Menghasilkan metadata untuk semua entitas yang diaktifkan REST yang ditentukan dalam konfigurasi runtime
  • Mengkompilasi metadata tersebut ke dalam skema OpenAPI yang valid
  • Mengekspos skema melalui UI visual (Swagger) atau sebagai file JSON berseri
  • Memfilter skema untuk memperlihatkan hanya metode dan bidang HTTP yang dapat diakses untuk peran tertentu

Dokumen deskripsi OpenAPI

Penyusun API Data menghasilkan dokumen deskripsi OpenAPI menggunakan konfigurasi runtime dan metadata database untuk setiap entitas yang diaktifkan REST.

Skema ini dibangun menggunakan SDK OpenAPI.NET dan sesuai dengan Spesifikasi OpenAPI v3.0.1. Ini output sebagai dokumen JSON.

Anda dapat mengakses dokumen OpenAPI di:

GET /{rest-path}/openapi

Nota

Secara default, rest-path adalah api. Nilai ini dapat dikonfigurasi. Lihat Konfigurasi REST untuk detailnya.

OpenAPI yang menyadari izin

Mulai dab 2.0, dokumen OpenAPI mencerminkan izin aktual yang dikonfigurasi untuk setiap entitas. Alih-alih mendokumentasikan setiap metode HTTP yang mungkin, skema yang dihasilkan hanya menunjukkan metode dan bidang yang dapat diakses peran tertentu.

Bagaimana izin dipetakan ke metode HTTP

DAB menerjemahkan izin entitas ke dalam visibilitas metode HTTP dalam dokumen OpenAPI:

Tindakan izin Metode HTTP ditampilkan
read GET
create POST
create + update PUT, PATCH
delete DELETE

Misalnya, jika peran anonymous hanya memiliki izin read pada entitas Book, dokumen OpenAPI untuk peran anonim hanya menunjukkan operasi GET untuk /api/Book. Operasi POST, PUT, PATCH, dan DELETE dihilangkan sepenuhnya.

Pemfilteran tingkat lapangan

Ketika perizinan menyertakan aturan exclude atau tingkat include bidang, skema OpenAPI mencerminkan batasan tersebut. Hanya bidang yang dapat diakses oleh peran pengguna yang muncul dalam skema permintaan dan tanggapan. Pemfilteran ini memberikan konsumen gambaran yang akurat tentang apa yang diterima dan dikembalikan oleh API sesuai dengan peran mereka.

Jalur OpenAPI yang ditentukan oleh peran

DAB menyediakan endpoint OpenAPI yang khusus untuk peran sehingga Anda bisa memeriksa skema untuk peran yang dikonfigurasi.

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

Jalur dasar /openapi mengembalikan tampilan anonim default. Setiap jalur yang spesifik untuk peran menghasilkan skema yang telah disaring sesuai izin peran tersebut.

Penting

Jalur OpenAPI khusus peran (/openapi/{role}) hanya tersedia dalam mode Pengembangan. Dalam mode Produksi, titik akhir ini dinonaktifkan untuk mencegah enumerasi peran. Hanya jalur dasar /openapi yang tersedia dalam mode Produksi.

Nota

Titik akhir khusus peran mengembalikan 404 Not Found jika peran tidak memiliki izin entitas yang dikonfigurasi di mana saja dalam konfigurasi runtime. Hanya peran yang memiliki setidaknya satu permissions entri pada setidaknya satu entitas yang menghasilkan dokumen OpenAPI.

Example

Pertimbangkan konfigurasi izin ini:

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

Dengan konfigurasi ini:

  • /api/openapi/anonymous menunjukkan hanya GET /api/Book dengan bidang respons id, title, dan year.
  • /api/openapi/authenticated menunjukkan operasi GET, POST, PUT, PATCH, dan DELETE pada /api/Book dengan semua bidang.

Antarmuka Pengguna Swagger

Antarmuka pengguna Swagger menyediakan tampilan INTERAKTIF berbasis web API berdasarkan skema OpenAPI.

Dalam Development mode, penyusun DATA API mengekspos antarmuka pengguna Swagger di:

GET /swagger

Titik akhir ini tidak ditumpuk di bawah rest-path untuk menghindari konflik dengan entitas yang ditentukan pengguna.

  • Last updated on