Batasan fitur OpenAPI

Cloud Endpoints hanya menerima Spesifikasi OpenAPI versi 2.

Bagian berikut menjelaskan batasan fitur OpenAPI di Endpoint.

Cakupan diabaikan

Meskipun Endpoints menerima dokumen OpenAPI yang memiliki cakupan yang ditentukan dalam objek skema keamanan, saat permintaan dikirim ke API Anda, baik Extensible Service Proxy (ESP), Extensible Service Proxy V2 (ESPv2), maupun Framework Cloud Endpoints tidak akan memeriksa cakupan yang ditentukan.

Beberapa persyaratan keamanan

Anda dapat menentukan lebih dari satu persyaratan keamanan dalam dokumen OpenAPI. Bagian ini menjelaskan skema keamanan yang didukung ESP dan ESPv2.

Persyaratan keamanan yang berisi kunci API

ESP dan ESPv2 tidak mendukung persyaratan keamanan alternatif (logika ATAU) jika salah satu skema keamanan adalah kunci API. Misalnya, ESP dan ESPv2 tidak mendukung daftar persyaratan keamanan berikut:

security:
- petstore_auth: []
- api_key: []

Definisi ini memerlukan operasi untuk menerima permintaan yang mengikuti persyaratan petstore_auth atau persyaratan api_key.

Namun, perlu diperhatikan bahwa ESP dan ESPv2 mendukung konjungsi persyaratan keamanan (AND logis), sehingga Anda dapat mewajibkan kunci API dan autentikasi OAuth2. Misalnya, daftar persyaratan keamanan berikut didukung:

security:
- petstore_auth: []
  api_key: []

Definisi ini memerlukan operasi untuk menerima permintaan yang secara bersamaan mengikuti persyaratan petstore_auth dan persyaratan api_key.

Persyaratan keamanan untuk OAuth2

ESP dan ESPv2 mendukung persyaratan keamanan alternatif keamanan (logika OR), tetapi hanya untuk skema keamanan autentikasi OAuth2. Misalnya, daftar persyaratan keamanan berikut didukung:

security:
  - firebase1: []
  - firebase2: []

Validasi definisi keamanan

ESP dan ESPv2 tidak memvalidasi bahwa semua persyaratan keamanan (baik di level API maupun level metode), juga ada di bagian securityDefinitions. Akibatnya, jika spesifikasi API menggunakan skema keamanan yang tidak ditentukan, permintaan yang tidak diautentikasi dapat berasal dari API, pada level tempat kunci keamanan yang tidak ditentukan dikonfigurasi. Pastikan semua kunci keamanan yang digunakan oleh API dan metodenya ditentukan berdasarkan definisi keamanan dalam dokumen OpenAPI Anda.

Pembuatan template jalur URL

Endpoint hanya mendukung parameter template jalur URL yang sesuai dengan seluruh segmen jalur (dipisahkan dengan garis miring /). Parameter template jalur URL yang sesuai dengan sebagian segmen jalur tidak didukung.

Misalnya, template jalur URL berikut didukung:

  • /items/{itemId}
  • /items/{itemId}/subitems

Template jalur URL berikut tidak didukung dan akan ditolak:

  • /items/overview.{format}
  • /items/prefix_{id}_suffix

Operasi pada jalur root URL /

Endpoints menerima dokumen OpenAPI yang menyertakan operasi pada jalur root /. Namun, permintaan di jalur root ditolak oleh ESP. Perhatikan bahwa batasan ini hanya untuk ESP, ESPv2 mendukung jalur root /.

Misalnya, cuplikan dokumen OpenAPI berikut diterima:

paths:
  /:
    post:
      operationId: "root"
      responses:
        200:
          description: "Success"
          schema:
            type: string

Namun, permintaan berikutnya untuk POST / ditolak dengan error berikut:

{
   "code": 5,
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "detail": "service_control",
           "stackEntries": []
       }
   ],
   "message": "Method does not exist."
}

Upload file

Endpoint tidak menerima type: file untuk parameter upload file, type: string harus digunakan sebagai gantinya.

Misalnya, cuplikan type: file berikut tidak diizinkan:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: file
          description: The file to upload.

Sedangkan hal berikut dengan type: string diizinkan:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: string
          description: The file to upload.

Parameter, skema, dan jenis

ESP dan ESPv2 mengabaikan sebagian besar definisi parameter dan jenis.

Endpoint menerima dokumen OpenAPI yang menyertakan definisi parameter dan jenis yang diperlukan, tetapi ESP dan ESPv2 tidak menerapkan definisi ini dan meneruskan permintaan masuk ke API Anda. Berikut adalah daftar sebagian yang memberikan contoh definisi yang tidak diterapkan oleh ESP dan ESPv2:

  • Parameter Data Formulir, seperti: 
    parameters:
- name: avatar
  in: formData
  description: "The avatar of the user"
  type: string
  • Parameter yang diperlukan, seperti: 
    parameters:
- name: message
  in: query
  description: "Message to send"
  required: true
  type: string
  • Format pengumpulan array, seperti: 
    parameters:
- name: items
  in: query
  description: "List of item IDs"
  required: true
  type: array
  items:
    type: string
  collectionFormat: tsv
  • Komposisi jenis, seperti: 
    definitions:
  base:
    properties:
      message:
        type: string
  extended:
    description: "Extends the base type"
    allOf:
    - $ref: "#/definitions/base"
    - type: object
      properties:
        extension:
          type: string
  • Objek respons yang berbeda per kode status, seperti: 
    responses:
  200:
    description: "Echo"
    schema:
      $ref: "#/definitions/EchoResponse"
  400:
    description: "Error"
    schema:
      type: string

Referensi jenis eksternal

Endpoint tidak mendukung referensi ke jenis di luar dokumen OpenAPI. Misalnya, Endpoints menolak dokumen OpenAPI yang menyertakan:

parameters:
- name: user
  description: User details
  in: body
  schema:
    $ref: "https://example.com/mytype.json"

Port kustom di alamat host layanan

Endpoint tidak mengizinkan port kustom di kolom host dokumen OpenAPI. Misalnya, Endpoint menolak dokumen OpenAPI seperti:

swagger: 2.0
host: example.com:8080
schemes:
- http

Batasan alias YAML

Endpoint dapat mendukung hingga 200 node alias YAML dalam dokumen OpenAPI. Jika ada lebih dari 200 alias YAML dalam dokumen OpenAPI, sebaiknya dereferensikan alias jika memungkinkan untuk mematuhi batas ini.

Bug yang diketahui

Dokumen OpenAPI ditolak

Saat Anda men-deploy dokumen OpenAPI menggunakan gcloud endpoints services deploy, Endpoints akan menolak dokumen OpenAPI yang menyertakan:

  • Parameter isi array, seperti: 
    parameters:
- name: message
  description: "Message to echo"
  in: body
  schema:
    type: array
    items:
      type: string
  • Jalur dengan garis miring di akhir, misalnya: 
    paths:
  "/echo/":
    post:
      description: "Echo back a given message."

    Untuk memperbaiki masalah ini, hapus garis miring di akhir dari /echo/:

    paths:
  "/echo":
    post:
      description: "Echo back a given message."

Batasan definisi kunci API

Saat menentukan kunci API di objek definisi keamanan dalam dokumen OpenAPI, Endpoints memerlukan salah satu skema berikut:

  • name adalah key dan in adalah query
  • name adalah api_key dan in adalah query
  • name adalah x-api-key dan in adalah header

Contoh:

"securityDefinitions": {
  "api_key_0": {
        "type": "apiKey",
        "name": "key",
        "in": "query"
    },
  "api_key_1": {
        "type": "apiKey",
        "name": "api_key",
        "in": "query"
    }
  "api_key_2": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
    },
}

Saat Anda men-deploy dokumen OpenAPI dengan jenis definisi keamanan kunci API lainnya, Endpoints mungkin menerimanya dan menampilkan peringatan. Namun, definisi keamanan kunci API diabaikan dalam permintaan masuk.