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 dari opsi berikut:

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

Menambahkan spesifikasi saat membuat versi

Dengan menggunakan UI saja, Anda dapat menambahkan spesifikasi API saat membuat versi. Anda dapat memberikan URL ke spesifikasi yang dapat diakses 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. Saat mencapai halaman Add a new version, Anda dapat menambahkan file spesifikasi ke versi tersebut (opsional):
1. Masukkan nama tampilan untuk file spesifikasi. Anda dapat menggunakan nama apa pun yang diinginkan.
2. Pilih jenis file spesifikasi. Jenis spesifikasi adalah atribut sistem yang dapat dikonfigurasi. Lihat juga Atribut sistem.
3. Sediakan URI yang mengarah ke file spesifikasi API valid yang dapat Anda akses, atau jelajahi file spesifikasi API di sistem Anda.
  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.
Selesaikan pengisian halaman Tambahkan versi baru, lalu klik Buat setelah selesai.

Menambahkan spesifikasi ke versi yang sudah ada

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

Konsol

Untuk menambahkan spesifikasi secara langsung ke versi:

Di konsol Google Cloud, buka halaman API hub.
Buka hub API
Klik API.
Temukan API dengan versi yang ingin Anda modifikasi. 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 diinginkan.
Pilih jenis file spesifikasi. Jenis spesifikasi adalah atribut sistem yang dapat dikonfigurasi. Lihat juga Atribut sistem.
Sediakan URI yang mengarah ke file spesifikasi API valid yang dapat Anda akses, atau jelajahi file spesifikasi API di sistem Anda.
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 Add API spec:

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 hub API 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 yang dihasilkan sistem 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 link ke spesifikasi. Lihat contoh REST.

Contoh REST

Dalam contoh ini, buat spesifikasi baru di hub API dengan spesifikasi OpenAPI berenkode Base64. Setelah diupload, hub API mengurai spesifikasi dan membuat entity spesifikasi baru yang menyertakan metadata deskriptif serta serangkaian 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"
}

Mencantumkan spesifikasi

Bagian ini menjelaskan cara menampilkan 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 Versions, cari versi yang ingin Anda periksa.
Pilih versi.
Spesifikasi apa pun yang ditautkan ke versi tersebut tercantum di bagian File spesifikasi.

REST

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

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 hub API 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 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 Versions, cari versi yang ingin Anda periksa.
Pilih versi.
Di bagian Specification file, pilih spesifikasi untuk melihat detailnya.

REST

Untuk melihat detail spesifikasi, gunakan API Get spesifikasi details:

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 hub API 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.
Temukan API dengan versi yang berisi spesifikasi yang ingin Anda hapus. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
Klik API untuk melihat detailnya.
Di tab Versions, cari versi yang berisi spesifikasi yang ingin Anda hapus.
Pilih versi.
Di bagian Specification file, pilih Delete dari menu Tindakan di baris spesifikasi yang ingin dihapus.
Klik Delete.

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 hub API disediakan.
API_ID: ID unik resource API.
VERSION_ID: ID unik versi.
SPEC_ID: ID unik spesifikasi yang akan dihapus.

Mengedit spesifikasi

Anda dapat mengedit beberapa atribut spesifikasi. Untuk daftar atribut yang dapat Anda perbarui, lihat API patch spesifikasi versi.

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 hub API disediakan.
API_ID: ID unik resource API.
VERSION_ID: ID unik versi.
SPEC_ID: ID unik spesifikasi.
Request Body: 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 spesifikasi Open API API Anda. Lihat Memvalidasi spesifikasi API.

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 Versions, 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.
Temukan API dengan versi yang berisi spesifikasi yang ingin Anda hapus. Gunakan Filter untuk menentukan kata kunci guna memfilter daftar API. Jika perlu, gunakan Penelusuran untuk menemukan API.
Klik API untuk melihat detailnya.
Di tab Versions, 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 hub API disediakan.
API_ID: ID unik resource API.
VERSION_ID: ID unik versi.
SPEC_ID: ID unik spesifikasi.

Contoh output:

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