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 baru OpenAPI 3.x
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 hanya dapat menentukan ekstensi x-google-endpoint pada satu server.
Untuk Cloud Endpoints, nama host diperlukan, sehingga 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, semua file harus menentukan server dengan ekstensi x-google-endpoint.
Selain itu, semua server dengan ekstensi x-google-endpoint harus menggunakan host yang sama di URL server, dan konfigurasi x-google-endpoint harus sama 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 (logis OR) jika salah satu skemanya adalah kunci API. Cloud Endpoints mendukung konjungsi (logis AND), sehingga Anda dapat mewajibkan kunci API dan autentikasi OAuth2.
Persyaratan keamanan untuk OAuth2: Cloud Endpoints mendukung persyaratan keamanan alternatif (logis OR) untuk skema autentikasi OAuth2 yang berbeda. Cloud Endpoints tidak mendukung konjungsi (logis AND) 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 menolak spesifikasi tersebut. Hal ini berbeda dengan OpenAPI 2.0, yang hanya menghasilkan peringatan.
Templating 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, dan 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 harus berjenis tidak berulang.