Batasan fitur OpenAPI

Saat ini, Cloud Endpoints hanya menerima Spesifikasi OpenAPI versi 2.

Bagian di bawah ini menjelaskan batasan fitur OpenAPI di Endpoint.

Cakupan diabaikan

Meskipun Endpoint menerima dokumen OpenAPI dengan cakupan yang ditetapkan dalam objek skema keamanan, saat permintaan dikirim ke API Anda, Extensible Service Proxy (ESP) maupun Cloud Endpoints Frameworks tidak akan memeriksa cakupan yang ditentukan.

Berbagai persyaratan keamanan

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

Persyaratan keamanan yang berisi kunci API

ESP tidak mendukung persyaratan keamanan alternatif (OR) jika salah satu skema keamanan berupa kunci API. Misalnya, ESP 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 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 mendukung persyaratan keamanan alternatif keamanan (OR logis), tetapi hanya untuk skema keamanan autentikasi OAuth2. Misalnya, daftar persyaratan keamanan berikut telah didukung:

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

Validasi definisi keamanan

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

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 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 /

Endpoint menerima dokumen OpenAPI yang mencakup operasi di jalur root /. Namun, permintaan pada 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 mengabaikan sebagian besar definisi parameter dan jenis.

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

  • 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 koleksi 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, Endpoint 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

Endpoint tidak mengizinkan port kustom di kolom host dalam 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 batalkan referensi alias jika memungkinkan untuk mematuhi batasan ini.

Bug yang diketahui

Dokumen OpenAPI ditolak

Saat Anda men-deploy dokumen OpenAPI menggunakan gcloud endpoints services deploy, Endpoint 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 dari /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, Endpoint 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, Endpoint mungkin menerimanya dan menampilkan peringatan. Namun, definisi keamanan kunci API akan diabaikan dalam permintaan masuk.

Portal Cloud Endpoints tidak merender jenis komposisi

Meskipun Endpoint menerima dokumen OpenAPI dengan jenis komposisi, yaitu jenis dengan allOf dalam definisi, Portal Endpoint tidak membuat dokumentasi untuk jenis komposisi.