Halaman ini diterjemahkan oleh Cloud Translation API.

Batasan fitur OpenAPI 3.x

Dokumen ini menjelaskan batasan fitur untuk menggunakan OpenAPI 3.x dengan API Gateway.

Untuk mengetahui informasi selengkapnya tentang versi spesifikasi OpenAPI yang didukung, lihat Ringkasan OpenAPI.

Batasan OpenAPI 3.x Baru

Bagian ini menjelaskan batasan untuk fitur baru di OpenAPI 3.x.

Server

OpenAPI 3.x mendukung beberapa objek server untuk menentukan host dan jalur dasar. Namun, API Gateway mengandalkan satu objek server, yang diidentifikasi oleh ekstensi x-google-endpoint, untuk mengonfigurasi layanan.

Meskipun Anda dapat menentukan beberapa server, API Gateway hanya mempertimbangkan server yang berisi ekstensi x-google-endpoint, dan hanya mengizinkan satu server tersebut. Untuk API Gateway, URL server tidak diperlukan, jadi Anda dapat tidak menentukan server atau menentukan satu server dengan ekstensi x-google-endpoint.

Misalnya, definisi berikut valid untuk API Gateway:

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

Definisi berikut tidak valid karena berisi beberapa ekstensi x-google-endpoint:

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

Definisi berikut valid untuk API Gateway, tetapi API Gateway mengabaikan objek server:

servers:
  - url: https://example.com

Server di Beberapa File

Jika Anda mengupload beberapa file OpenAPI dan salah satu file berisi server dengan ekstensi x-google-endpoint, maka semua file juga harus memiliki server yang ditentukan dengan ekstensi x-google-endpoint yang identik dan host yang identik di URL server. Basepath dapat berbeda di antara file.

URL relatif

Untuk API Gateway, URL relatif dalam objek servers diperlakukan sebagai basepath dengan sendirinya karena nama host tidak diperlukan dalam spesifikasi. Hal ini berbeda dengan perilaku OpenAPI standar, yang menyelesaikan URL relatif terhadap server yang menghosting definisi OpenAPI. Misalnya, API Gateway memperlakukan url: /v1 sebagai basepath.

Basepath harus dimulai dengan '/'. API Gateway menolak URL yang tidak memiliki skema atau dimulai dengan '/' untuk menunjukkan basepath.

Ekstensi yang Tidak Didukung

API Gateway tidak mendukung ekstensi x-google-allow untuk OpenAPI 3.x.

Batas ukuran file

API Gateway menerapkan batas ukuran total 10 MB dan batas jumlah file 50 untuk file OpenAPI 3.x yang diupload.

Batasan yang sudah ada

Bagian ini menjelaskan batasan yang diwariskan dari OpenAPI 2.0 yang juga berlaku untuk OpenAPI 3.x.

Cakupan diabaikan

Meskipun API Gateway menerima dokumen OpenAPI dengan cakupan yang ditentukan dalam objek skema keamanan, API Gateway tidak memeriksa atau menerapkan cakupan ini.

Beberapa persyaratan keamanan

Persyaratan Kunci API: API Gateway tidak mendukung persyaratan keamanan alternatif (OR logis) jika salah satu skemanya adalah kunci API. Namun, API Gateway mendukung konjungsi (AND logis), yang memungkinkan Anda mewajibkan kunci API dan token OAuth2.
Persyaratan OAuth2: API Gateway mendukung persyaratan keamanan alternatif (OR logis) untuk berbagai skema keamanan OAuth2. API Gateway tidak mendukung konjungsi (AND logis) kecuali jika persyaratan keamanan tambahan adalah kunci API.
Keamanan Opsional: Anda dapat menggunakan persyaratan keamanan kosong (- {}) untuk membuat keamanan opsional untuk kunci API, tetapi API Gateway tidak mendukung hal ini untuk OAuth.

Validasi definisi keamanan

API Gateway akan menolak spesifikasi OpenAPI 3.x yang menggunakan persyaratan keamanan tanpa definisi yang sesuai di bagian securityDefinitions.

Pembuatan template jalur URL

API Gateway hanya mendukung parameter template jalur URL yang merepresentasikan seluruh segmen jalur, misalnya, /items/{itemId}. API Gateway tidak mendukung dan menolak parameter yang sesuai dengan segmen parsial, misalnya, /items/prefix_{id}_suffix.

Parameter, skema, isi permintaan, dan jenis

API Gateway menerima dokumen OpenAPI dengan berbagai definisi parameter dan jenis (misalnya, parameter required dan format array), tetapi tidak menerapkannya. API Gateway meneruskan permintaan masuk ke API Anda, terlepas dari definisi ini.

API Gateway hanya mendukung jenis primitif dalam parameter permintaan.

Referensi jenis eksternal

API Gateway tidak mendukung referensi ke jenis di luar dokumen OpenAPI yang disediakan. Misalnya, API Gateway tidak mengizinkan dan menolak $ref yang mengarah ke URL eksternal.

Port kustom di alamat host

API Gateway tidak mengizinkan port kustom di kolom servers.url dokumen OpenAPI.

Batasan alias YAML

Dokumen OpenAPI yang dikirimkan ke API Gateway dapat memiliki maksimum 200 node alias YAML.