Halaman ini diterjemahkan oleh Cloud Translation API.

Mengelola spesifikasi API

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Dokumen ini menjelaskan cara mengelola spesifikasi API di hub API. Lihat juga Pengantar spesifikasi API.

Menambahkan spesifikasi API ke versi

Anda dapat menambahkan satu atau beberapa spesifikasi API ke versi API. Pilih salah satu opsi berikut:

Menambahkan spesifikasi saat membuat versi
Menambahkan spesifikasi ke versi yang sudah ada

Menambahkan spesifikasi saat membuat versi

Hanya dengan UI, Anda dapat menambahkan spesifikasi API di saat yang sama membuat versi. Anda dapat memberikan URL ke spesifikasi yang dapat Anda akses atau mengupload file spesifikasi langsung dari sistem Anda.

Konsol

Untuk menambahkan spesifikasi ke versi baru:

Ikuti langkah-langkah yang tercantum di Membuat versi API untuk memulai. Jika Anda buka halaman Add a new version, Anda dapat menambahkan file spesifikasi ke versi:
1. Masukkan nama tampilan untuk file spesifikasi. Anda dapat menggunakan nama apa pun yang Anda inginkan.
2. Pilih jenis file spesifikasi. Jenis spesifikasi adalah sistem yang dapat dikonfigurasi . Lihat juga Atribut sistem.
3. Berikan URI yang menunjuk ke file spesifikasi API valid yang bisa Anda akses, atau cari file spesifikasi API di sistem Anda.
4. (Opsional) Jika Anda ingin menerapkan validasi ketat pada spesifikasi yang diupload, pilih Kotak centang Batasi upload file spesifikasi yang berisi error. Ketika opsi ini dipilih, spesifikasi yang berisi error validasi tidak akan diupload. Secara {i>default<i}, spesifikasi yang berisi kesalahan telah diupload.
Selesaikan pengisian halaman Add a new version, lalu klik Create ketika Anda sudah selesai.

Menambahkan spesifikasi ke versi yang sudah ada

Anda dapat menggunakan UI atau REST API untuk menambahkan spesifikasi API ke versi yang sudah ada.

Konsol

Untuk menambahkan spesifikasi secara langsung ke versi:

Di konsol Google Cloud, buka halaman API hub.
Buka hub API
Klik API.
Cari API dengan versi yang ingin Anda ubah. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
Pilih API.
Klik Tambahkan file spesifikasi.
Masukkan nama tampilan untuk file spesifikasi. Anda dapat menggunakan nama apa pun yang Anda inginkan.
Pilih jenis file spesifikasi. Jenis spesifikasi adalah sistem yang dapat dikonfigurasi . Lihat juga Atribut sistem.
Berikan URI yang mengarah ke file spesifikasi API valid yang aksesnya Anda miliki, atau cari file spesifikasi API di sistem Anda.
(Opsional) Jika Anda ingin menerapkan validasi ketat pada spesifikasi yang diupload, pilih Kotak centang Batasi upload file spesifikasi yang berisi error. Ketika opsi ini dipilih, spesifikasi yang berisi error validasi tidak akan diupload. Secara {i>default<i}, spesifikasi yang berisi kesalahan telah diupload.
Pilih versi yang akan ditambahi file spesifikasi.
Klik Create.
Catatan: Untuk rilis pratinjau publik, penguraian spesifikasi API hanya didukung untuk spesifikasi OpenAPI (v.2.0, v3.0, dan v3.1) dalam format JSON dan YAML.

REST

Untuk menambahkan spesifikasi API ke versi, gunakan API Tambahkan spesifikasi API:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

Ganti kode berikut:

API_PROJECT: Nama project host hub API Anda. Project host dipilih saat hub API disediakan.
API_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
API_ID: ID unik resource API.
VERSION_ID: ID versi yang dilampirkan ke resource API.
SPEC_ID: (Opsional) ID spesifikasi. Jika tidak diberikan, ID akan digunakan. Nama harus berupa string berisi 4-63 karakter, dengan karakter yang valid adalah /[a-z][0-9]-/.
DATA_FILE or URI: File berenkode Base64 yang berisi spesifikasi API yang valid atau menautkan ke spesifikasi. Lihat contoh REST.

Contoh REST

Dalam contoh ini, buat spesifikasi baru di hub API dengan enkode Base64 Spesifikasi OpenAPI. Setelah diupload, hub API akan mengurai spesifikasi dan membuat entity spesifikasi baru yang menyertakan {i>metadata<i} deskriptif ditambah kumpulan entitas operasi dan definisi.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

Contoh output:

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

Untuk menampilkan detail spesifikasi:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

Output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Cantumkan spesifikasi

Bagian ini menjelaskan cara mencantumkan spesifikasi yang terkait dengan versi API.

Konsol

Untuk mencantumkan spesifikasi dengan UI:

Di konsol Google Cloud, buka halaman API hub.
Buka hub API
Klik API.
Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
Klik API untuk melihat detailnya.
Di tab Versi, cari versi yang ingin Anda periksa.
Pilih versi.
Spesifikasi apa pun yang ditautkan ke versi tercantum di bagian File spesifikasi.

REST

Untuk mencantumkan spesifikasi yang terkait dengan versi API, gunakan API ListSpecification:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Ganti kode berikut:

HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat hub API disediakan.
HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
API_ID: ID unik resource API.
VERSION_ID: ID unik versi.

Dapatkan detail spesifikasi

Bagian ini menjelaskan cara mendapatkan detail tentang spesifikasi API yang terkait dengan versi.

Konsol

Untuk melihat detail spesifikasi menggunakan UI:

Di konsol Google Cloud, buka halaman API hub.
Buka hub API
Klik API.
Temukan API dengan versi yang berisi spesifikasi yang ingin Anda periksa. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
Klik API untuk melihat detailnya.
Di tab Versi, cari versi yang ingin Anda periksa.
Pilih versi.
Di bagian Specification file, pilih spesifikasi untuk melihat detailnya.

REST

Untuk melihat detail spesifikasi, gunakan API Mendapatkan detail spesifikasi:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Ganti kode berikut:

HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat hub API disediakan.
HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
API_ID: ID unik resource API.
VERSION_ID: ID unik versi.
SPEC_ID: ID unik spesifikasi.

Contoh output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

Menghapus spesifikasi API

Bagian ini menjelaskan cara menghapus spesifikasi API dari versi. Menghapus spesifikasi juga akan menghapus operasi terkait dari versi.

Konsol

Untuk menghapus resource API dengan UI:

Di konsol Google Cloud, buka halaman API hub.
Buka hub API
Klik API.
Cari API dengan versi yang berisi spesifikasi yang ingin dihapus. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
Klik API untuk melihat detailnya.
Pada tab Versi, cari versi yang berisi spesifikasi yang ingin dihapus.
Pilih versi.
Di bagian File spesifikasi, pilih Hapus dari menu Tindakan di baris spesifikasi yang ingin Anda hapus.
Klik Hapus.

REST

Untuk menghapus resource API dari hub API, gunakan API Delete API resource:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

Ganti kode berikut:

HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat hub API disediakan.
HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
API_ID: ID unik resource API.
VERSION_ID: ID unik versi.
SPEC_ID: ID unik spesifikasi yang akan dihapus.

Edit metadata spesifikasi

Anda dapat mengedit beberapa metadata yang terkait dengan spesifikasi yang disimpan di hub API. Untuk daftar {i>metadata<i} yang dapat Anda edit, lihat Spec patch API.

Konsol

Anda dapat melakukan perubahan pada spesifikasi yang sudah ada melalui Konsol Google Cloud. Misalnya, Anda dapat mengubah nama tampilan, mengunggah file spesifikasi baru, mengubah jenis file, lalu edit atribut:

Di konsol Google Cloud, buka halaman API hub.
Buka hub API
Klik API.
Cari API dengan versi yang berisi spesifikasi yang ingin Anda edit. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
Klik API untuk melihat detailnya.
Pada tab Versi, cari versi yang berisi spesifikasi yang ingin Anda edit.
Pilih versi.
Di halaman Versi, cari spesifikasi yang ingin Anda edit.
Pilih Edit dari menu Tindakan di baris spesifikasi yang ingin diedit.
Di panel pengeditan spesifikasi, Anda dapat mengubah spesifikasi berikut {i>metadata<i}:
- Nama tampilan
- Jenis file spesifikasi
- Dokumen spesifikasi: Jelajahi file spesifikasi baru untuk diupload.
- Atribut yang ditentukan pengguna (jika ada)
Klik Simpan.

REST

Untuk mengedit spesifikasi dengan REST API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

Ganti kode berikut:

HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat hub API disediakan.
HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
API_ID: ID unik resource API.
VERSION_ID: ID unik versi.
SPEC_ID: ID unik spesifikasi.
Isi Permintaan: Gunakan isi permintaan untuk menentukan atribut yang akan diubah. Lihat Definisi resource spesifikasi.

Melihat hasil lint spesifikasi

Hub API menyediakan linter (validator) bawaan (Spectral) yang memvalidasi API Anda Spesifikasi API terbuka. Lihat Memvalidasi spesifikasi API.

Di konsol Google Cloud, buka halaman API hub.
Buka hub API
Klik API.
Cari API dengan versi yang berisi spesifikasi yang ingin Anda periksa. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
Klik API untuk melihat detailnya.
Pada tab Versi, cari versi yang berisi spesifikasi yang ingin Anda periksa.
Klik Results di kolom Lint untuk melihat hasil lint.

Mendapatkan konten spesifikasi

Fitur ini memungkinkan Anda meninjau konten spesifikasi yang diupload ke hub API.

Konsol

Untuk melihat detail spesifikasi menggunakan UI:

Di konsol Google Cloud, buka halaman API hub.
Buka hub API
Klik API.
Cari API dengan versi yang berisi spesifikasi yang ingin dihapus. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
Klik API untuk melihat detailnya.
Pada tab Versi, cari versi yang berisi spesifikasi yang ingin Anda periksa.
Klik nama spesifikasi untuk melihat kontennya.

REST

API mengambil konten mentah berenkode Base64 dari spesifikasi API yang diupload ke hub API. Gunakan API Get spesifikasi contents:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Ganti kode berikut:

HUB_PROJECT: Nama project host hub API Anda. Project host dipilih saat hub API disediakan.
HUB_LOCATION: Lokasi project host. Lokasi dipilih saat API telah disediakan.
API_ID: ID unik resource API.
VERSION_ID: ID unik versi.
SPEC_ID: ID unik spesifikasi.

Contoh output:

{
  "contents": "Base64-encoded file contents"
}