Batasan fitur OpenAPI 2.0

Bagian berikut menjelaskan batasan fitur OpenAPI 2.0 di Endpoints.

Cakupan diabaikan

Meskipun Endpoints menerima dokumen OpenAPI yang memiliki cakupan yang ditentukan dalam objek skema keamanan, saat permintaan dikirim ke API Anda, Extensible Service Proxy (ESP), Extensible Service Proxy V2 (ESPv2), maupun Cloud Endpoints Frameworks tidak 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 (OR logis) 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 mengharuskan operasi menerima permintaan yang mengikuti persyaratan petstore_auth atau persyaratan api_key.

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

security:
- petstore_auth: []
  api_key: []

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

Persyaratan keamanan untuk OAuth2

ESP dan ESPv2 mendukung persyaratan keamanan alternatif (OR logis) keamanan, 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 tingkat API maupun tingkat metode) juga ada di bagian securityDefinitions. Akibatnya, jika spesifikasi API menggunakan skema keamanan yang tidak ditentukan, permintaan yang tidak diautentikasi dapat masuk melalui API, pada tingkat tempat kunci keamanan yang tidak ditentukan dikonfigurasi. Pastikan semua kunci keamanan yang digunakan oleh API dan metodenya ditentukan dalam definisi keamanan di dokumen OpenAPI Anda.

Pembuatan template jalur URL

Endpoint hanya mendukung parameter template jalur URL yang sesuai dengan seluruh segmen jalur (dibatasi oleh garis miring /). Parameter template jalur URL yang sesuai dengan segmen jalur parsial 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

Endpoints 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 jenis dan parameter yang diperlukan, tetapi ESP dan ESPv2 tidak menerapkan definisi ini dan meneruskan permintaan masuk ke API Anda. Berikut adalah daftar parsial 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 huruf, 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

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

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

Port kustom di alamat host layanan

Endpoints tidak mengizinkan port kustom di kolom host dokumen OpenAPI. Misalnya, Endpoints 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 hapus referensi alias jika memungkinkan untuk mematuhi batas ini.

Bug yang diketahui

Berikut adalah daftar masalah umum.

Dokumen OpenAPI ditolak

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

  • 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 /echo/:

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

Batasan definisi kunci API

Saat menentukan kunci API dalam objek definisi keamanan di 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.