Halaman ini diterjemahkan oleh Cloud Translation API.

Memodifikasi gateway untuk menggunakan OpenAPI 3.x

Halaman ini menjelaskan cara mengubah gateway API yang ada untuk menggunakan spesifikasi OpenAPI 3.x bagi konfigurasi API-nya.

Sebelum memulai

Pastikan Anda memiliki instance API Gateway yang sudah dikonfigurasi dengan spesifikasi OpenAPI 2.0.
Instal gcloud CLI. Untuk mengetahui informasi selengkapnya, lihat Menginstal Google Cloud CLI.

Mengubah konfigurasi API untuk menggunakan OpenAPI 3.x

Untuk mengubah konfigurasi API Gateway OpenAPI 2.0 yang ada agar menggunakan OpenAPI 3.x, selesaikan langkah-langkah berikut:

Menemukan konfigurasi API saat ini

Temukan konfigurasi API yang terkait dengan gateway Anda.

Jelaskan instance API Gateway Anda:

gcloud api-gateway gateways describe GATEWAY_ID --project=PROJECT_ID --location=GATEWAY_LOCATION

Ganti kode berikut:

GATEWAY_ID: ID gateway Anda.
PROJECT_ID: Project ID Google Cloud Anda.
GATEWAY_LOCATION: Lokasi gateway Anda.

Output menampilkan jalur apiConfig, misalnya:

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-gateway-config
createTime: '2025-03-25T02:49:58.641650649Z'
defaultHostname: my-gateway-a1b2c3d4.uc.gateway.dev
displayName: My gateway
name: projects/my-project/locations/us-west1/gateways/my-new-gateway
state: ACTIVE
updateTime: '2025-03-25T02:51:52.674308428Z'

Mendapatkan dokumen OpenAPI

Untuk mendapatkan dokumen OpenAPI bagi konfigurasi API yang Anda identifikasi:

Jelaskan konfigurasi API:

gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID --project=PROJECT_ID --view=FULL

Ganti kode berikut:

CONFIG_ID: ID konfigurasi API Anda.
API_ID: ID API Anda.
PROJECT_ID: Project ID Google Cloud Anda.

Output menampilkan bagian openapiDocuments, yang berisi konten berenkode base64 dari dokumen OpenAPI Anda:

createTime: '2024-02-16T21:11:36.293169474Z'
displayName: my-api-config
gatewayServiceAccount: projects/-/serviceAccounts/api-gateway-sa@my-sandbox.iam.gserviceaccount.com
name: projects/my-project-id/locations/global/apis/my-api/configs/my-gateway-config
openapiDocuments:
-   document:
    contents: IyBvc...
    path: apigateway-config.yaml
serviceConfigId: my-api-config-0a1fjkfeb7t8z
state: ACTIVE
updateTime: '2024-02-16T21:13:45.626771120Z'

Mendekode dokumen OpenAPI

Untuk mendekode konten dokumen OpenAPI berenkode base64:

Dekode nilai contents:

echo 'IyBvc...' | base64 -d

Ganti IyBvc... dengan nilai contents sebenarnya dari langkah sebelumnya.

Output menampilkan dokumen OpenAPI 2.0 Anda, misalnya:

swagger: '2.0'
info:
  title: API_ID
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0

Mengonversi dokumen OpenAPI ke OpenAPI 3.x

Anda dapat menggunakan alat untuk mengonversi dokumen OpenAPI 2.0 ke OpenAPI 3.x. Misalnya, Swagger Editor menyediakan utilitas konversi.

Setelah konversi awal ke OpenAPI 3.x, terapkan perubahan tambahan secara manual pada dokumen agar selaras dengan OpenAPI 3.x dan pastikan kompatibilitas dengan ekstensi dan fitur API Gateway. Untuk mengetahui detail selengkapnya tentang ekstensi OpenAPI 3.x yang didukung di API Gateway, lihat Ekstensi OpenAPI 3.x di API Gateway.

Tabel berikut menjelaskan perubahan yang diperlukan:

Fitur	OpenAPI 2.0	OpenAPI 3.x	Deskripsi perubahan
Kunci API	`securityDefinitions`	`securitySchemes`	Kunci API menggunakan dukungan kunci API OpenAPI langsung. Alat konversi biasanya menanganinya secara otomatis. Tidak diperlukan perubahan manual.
Autentikasi JWT	`x-google-audiences`, dll.	`x-google-auth`	Di ekstensi OpenAPI 2.0, Anda menentukan konfigurasi OAuth dengan ekstensi individual pada instance `securityDefinition`. Alat konversi mengonversi instance skema keamanan ke `#/components/securitySchemes` dan membiarkan ekstensi. Ubah ekstensi ini secara manual agar menjadi turunan dari `x-google-auth` dan hapus awalan `x-google-`. Nilainya tetap sama.
Kuota	`x-google-management`, `x-google-quota`	`x-google-api-management`, `x-google-quota`	Dalam ekstensi OpenAPI 2.0, Anda menentukan metrik dan kuota di `x-google-management` dan melampirkannya dengan `x-google-quota`. Alat konversi akan tetap menggunakan ekstensi ini. Pindahkan konfigurasi metrik dan kuota secara manual dari `x-google-management` ke `x-google-api-management`. Ubah konfigurasi untuk menggunakan kunci YAML, dan hapus `valueType`, `metricKind`, dan `unit`. Menghapus `metricCosts` dari instance `x-google-quota`.
Backend	`x-google-backend`	`x-google-api-management`, `x-google-backend`	Di ekstensi OpenAPI 2.0, Anda menentukan backend di `x-google-backend`, dan konfigurasi berlaku jika ditetapkan. Di ekstensi OpenAPI 3.x, Anda menentukan backend di `x-google-api-management`, lalu menerapkannya dengan `x-google-backend`. Alat konversi akan membiarkan ekstensi ini tetap ada. Pindahkan konfigurasi secara manual ke `x-google-api-management`. Ubah instance `x-google-backend` untuk mereferensikan konfigurasi tersebut.
Endpoint	`x-google-endpoints`	`x-google-endpoint`, `servers`	Dalam ekstensi OpenAPI 2.0, Anda menentukan konfigurasi endpoint di `x-google-endpoints`. Di ekstensi OpenAPI 3.x, Anda menggunakan `x-google-endpoint`, tetapi ini adalah ekstensi di `servers`, bukan di root. Alat konversi akan tetap membiarkan ekstensi ini. Pindahkan secara manual ke `servers` dan hapus kolom `name`. Contoh: # OpenAPI 2.0 x-google-endpoints: - name: "my-api.apigateway.my-project.cloud.goog" allowCors: True # OpenAPI 3.0.x servers: - url: https://my-api.apigateway.my-project.cloud.goog/ x-google-endpoint: allowCors: True
Nama API	`x-google-api-name`	`x-google-api-management`	Dalam ekstensi OpenAPI 2.0, Anda menentukan nama API di `x-google-api-name`. Di ekstensi OpenAPI 3.x, Anda menggunakan kolom `apiName` di `x-google-api-management`. Pindahkan konfigurasi ini secara manual ke `x-google-api-management`.
Izinkan semua traffic	`x-google-allow`	NOT SUPPORTED	Hapus ini dari dokumen OpenAPI. API Gateway tidak mendukungnya di OpenAPI 3.x.

Membuat konfigurasi API baru

Buat konfigurasi API baru menggunakan dokumen OpenAPI 3.x yang telah diubah.

Buat konfigurasi API:
```
gcloud api-gateway api-configs create NEW_CONFIG_ID --api=API_ID --project=PROJECT_ID --openapi-spec=NEW_API_DEFINITION
```
Ganti kode berikut:
- NEW_CONFIG_ID: ID baru untuk konfigurasi API Anda.
- API_ID: ID API Anda.
- PROJECT_ID: Project ID Google Cloud Anda.
- NEW_API_DEFINITION: Jalur ke file spesifikasi OpenAPI 3.x Anda.

Memperbarui gateway

Perbarui instance gateway Anda untuk mereferensikan konfigurasi API baru dari dokumen OpenAPI 3.x yang telah diubah.

Perbarui gateway:
```
gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION
```
Ganti kode berikut:
- GATEWAY_ID: ID gateway Anda.
- API_CONFIG: Jalur resource lengkap konfigurasi API baru Anda, misalnya: projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
- PROJECT_ID: Project ID Google Cloud Anda.
- GATEWAY_LOCATION: Lokasi gateway Anda.

Langkah berikutnya

Pelajari API Gateway lebih lanjut.
Jelajahi Spesifikasi OpenAPI.