Beperkingen voor OpenAPI-functies

Op dit moment accepteert Cloud Endpoints alleen versie 2 van de OpenAPI Specification.

In de onderstaande secties worden de beperkingen van OpenAPI-functies op Cloud Endpoints beschreven.

Alternatieve beveiligingsvereisten

Cloud Endpoints biedt geen ondersteuning voor alternatieve (logische OR) beveiligingsvereisten. De volgende lijst met beveiligingsvereisten wordt bijvoorbeeld niet ondersteund:

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

De bovenstaande definitie vereist dat een bewerking verzoeken accepteert die voldoen aan de petstore_auth-vereisten of de api_key-vereisten.

Houd er echter rekening mee dat Cloud Endpoints ondersteuning biedt aan gecombineerde beveiligingsvereisten (logische AND). De volgende lijst met beveiligingsvereisten wordt bijvoorbeeld ondersteund:

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

Deze definitie vereist dat een bewerking verzoeken accepteert die tegelijkertijd voldoen aan de petstore_auth-vereisten en de api_key-vereisten.

Templates van URL-paden

Cloud Endpoints ondersteunt alleen parameters van URL-padtemplates die overeenkomen met volledige padsegmenten (gescheiden door schuine strepen '/'). Parameters van URL-padtemplates die overeenkomen met gedeeltelijke padsegmenten worden niet ondersteund.

De volgende URL-padtemplates worden bijvoorbeeld ondersteund:

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

En de volgende URL-padtemplates worden niet ondersteund en worden afgekeurd:

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

Bewerkingen op URL-rootpad '/'

Cloud Endpoints accepteert OpenAPI-documenten met bewerkingen op het rootpad '/'. Verzoeken op het rootpad worden echter afgekeurd door de Extensible Service Proxy (ESP).

Het volgende fragment van een OpenAPI-document wordt bijvoorbeeld geaccepteerd:

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

Maar de daaropvolgende verzoeken voor POST / worden afgekeurd met de volgende fout:

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

Parameters, schema's en typen

Cloud Endpoints negeert de meeste parameter- en typedefinities.

Cloud Endpoints accepteert OpenAPI-documenten met vereiste parameter- en typedefinities, maar deze definities worden niet afgedwongen in inkomende verzoeken. Hieronder volgt een gedeeltelijke lijst met voorbeelden van de definities die Cloud Endpoints accepteert maar niet afdwingt.

  • Parameters van formuliergegevens, zoals:
    parameters:
    - name: avatar
      in: formData
      description: "The avatar of the user"
      type: string
  • Vereiste parameters, zoals:
    parameters:
    - name: message
      in: query
      description: "Message to send"
      required: true
      type: string
  • Indelingen voor matrixverzamelingen, zoals:
    parameters:
    - name: items
      in: query
      description: "List of item IDs"
      required: true
      type: array
      items:
        type: string
      collectionFormat: tsv
  • Typesamenstellingen, zoals:
    definitions:
      base:
        properties:
          message:
            type: string
      extended:
        description: "Extends the base type"
        allOf:
        - $ref: "#/definitions/base"
        - type: object
          properties:
            extension:
              type: string
  • Verschillende reactieobjecten per statuscode, zoals:
    responses:
      200:
        description: "Echo"
        schema:
          $ref: "#/definitions/EchoResponse"
      400:
        description: "Error"
        schema:
          type: string

Externe typereferenties

Cloud Endpoints ondersteunt geen referenties naar typen buiten een OpenAPI-document. Cloud Endpoints keurt bijvoorbeeld OpenAPI-documenten af die het volgende bevatten:

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

Bekende problemen

Afgekeurde OpenAPI-documenten

Wanneer u uw OpenAPI-document implementeert via gcloud endpoints services deploy, keurt Cloud Endpoints OpenAPI-documenten af die het volgende bevatten:

  • Body-parameters van matrices, zoals:
    parameters:
    - name: message
      description: "Message to echo"
      in: body
      schema:
        type: array
        items:
          type: string

Beperkingen van API-sleutels

Bij het opgeven van een API-sleutel in het object voor beveiligingsdefinities in uw OpenAPI-document, heeft Cloud Endpoints de volgende vereisten:

  • Het veld name moet key zijn.
  • Het veld in moet query zijn.

Voorbeeld:

"securityDefinitions": {
  "api_key": {
    "type": "apiKey",
    "name": "key",
    "in": "query"
  }

Wanneer u een OpenAPI-document implementeert met andere typen beveiligingsdefinities van API-sleutels, kan Cloud Endpoints deze accepteren en een waarschuwing weergeven. De beveiligingsdefinities van API-sleutels worden echter genegeerd bij inkomende verzoeken.