Dokumen ini menjelaskan batasan fitur untuk menggunakan OpenAPI 3.x dengan Endpoints.
Untuk mengetahui informasi selengkapnya tentang versi spesifikasi OpenAPI yang didukung, lihat Ringkasan OpenAPI.
Batasan OpenAPI 3.x baru
Bagian ini menjelaskan batasan untuk OpenAPI yang baru dengan dukungan OpenAPI 3.x.
Server
OpenAPI 3.x mendukung beberapa objek server untuk menentukan host dan jalur dasar. Namun, Cloud Endpoints hanya menggunakan satu objek server untuk mengonfigurasi nama host dan jalur dasar, yang diidentifikasi oleh ekstensi x-google-endpoint.
Meskipun Anda dapat menentukan beberapa server dalam spesifikasi OpenAPI, Cloud Endpoints hanya menggunakan server dengan ekstensi x-google-endpoint. Anda dapat menentukan ekstensi x-google-endpoint hanya di satu server.
Untuk Cloud Endpoints, nama host diperlukan, jadi hanya satu server yang harus memiliki ekstensi x-google-endpoint.
Misalnya, definisi server berikut valid untuk Cloud Endpoints:
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
- url: https://example.com
Definisi server berikut tidak valid untuk Endpoints:
servers:
- url: https://my-api-1.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
- url: https://my-api-2.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
Definisi berikut juga tidak valid untuk Cloud Endpoints:
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
Server di beberapa file
Jika Anda mengupload beberapa file OpenAPI, semua file harus mengikuti batasan bagian servers. Jika satu file berisi server dengan ekstensi x-google-endpoint, maka semua file harus menentukan server dengan ekstensi x-google-endpoint.
Selain itu, semua server dengan ekstensi x-google-endpoint harus menggunakan host yang identik di URL server, dan konfigurasi x-google-endpoint harus identik di semua file. Basepath di URL server dapat berbeda.
URL relatif
Cloud Endpoints memerlukan nama host, sehingga tidak mendukung URL relatif.
Ekstensi yang tidak didukung
OpenAPI 3.x tidak mendukung ekstensi x-google-allow.
Batasan yang sudah ada
Bagian ini menjelaskan batasan yang ada di OpenAPI 2.0 dan terus berlaku untuk OpenAPI 3.x.
Cakupan diabaikan
Meskipun Anda dapat menentukan cakupan dalam objek skema keamanan, ESP atau Cloud Endpoints Frameworks tidak memeriksanya.
Beberapa persyaratan keamanan
Anda dapat menentukan lebih dari satu persyaratan keamanan dalam dokumen OpenAPI.
Persyaratan keamanan dengan kunci API: Cloud Endpoints tidak mendukung persyaratan keamanan alternatif (OR logis) jika salah satu skemanya adalah kunci API. Cloud Endpoints mendukung konjungsi (AND logis), sehingga Anda dapat mewajibkan autentikasi kunci API dan OAuth2.
Persyaratan keamanan untuk OAuth2: Cloud Endpoints mendukung persyaratan keamanan alternatif (OR logis) untuk berbagai skema autentikasi OAuth2. Cloud Endpoints tidak mendukung konjungsi (AND logis) kecuali jika persyaratan keamanan tambahan adalah kunci API.
Persyaratan Keamanan Opsional: OpenAPI 3 mendukung keamanan opsional dengan menyertakan persyaratan kosong (
{}). Kunci API mendukung hal ini, tetapi OAuth tidak.
Validasi definisi keamanan
Untuk OpenAPI 3.x, penggunaan skema keamanan yang tidak ditentukan akan menghasilkan error, dan Cloud Endpoints akan menolak spesifikasi. Hal ini berbeda dengan OpenAPI 2.0, yang hanya menghasilkan peringatan.
Pembuatan template jalur URL
Cloud Endpoints hanya mendukung parameter template jalur URL yang sesuai dengan seluruh segmen jalur (dibatasi oleh /). Cloud Endpoints tidak mendukung parameter untuk segmen jalur parsial.
Misalnya, Cloud Endpoints mendukung /items/{itemId}, tetapi tidak mendukung /items/overview.{format}.
Operasi pada jalur root URL /
Meskipun dokumen OpenAPI menerima operasi pada jalur root /, Extensible Service Proxy menolak permintaan ke jalur root. Batasan ini tidak berlaku untuk ESPv2, yang mendukung jalur root.
Parameter, skema, isi permintaan, dan jenis
Extensible Service Proxy dan ESP mengabaikan sebagian besar parameter, skema, isi permintaan, dan definisi jenis. Extensible Service Proxy dan ESP tidak menerapkan parameter dan definisi jenis yang diperlukan, serta meneruskan permintaan ke API Anda.
Extensible Service Proxy dan ESP hanya mendukung jenis primitif dalam parameter permintaan.
Referensi jenis eksternal
Cloud Endpoints tidak mendukung referensi ke jenis di luar dokumen OpenAPI. Misalnya, Anda tidak dapat menggunakan $ref ke URL eksternal.
Port kustom di alamat host layanan
Anda tidak dapat menggunakan port kustom di url objek servers.
Batasan alias YAML
Dokumen OpenAPI dapat berisi maksimum 200 node alias YAML.
Isi permintaan yang tidak berulang
Anda hanya dapat menentukan satu requestBody per operasi, dan requestBody tersebut harus berjenis non-berulang.