Limitazioni delle funzioni OpenAPI

Attualmente, Cloud Endpoints accetta solo la versione 2 della specifica OpenAPI.

Le sezioni seguenti descrivono i limiti delle funzioni OpenAPI in Cloud Endpoints.

Requisiti di sicurezza alternativi

Cloud Endpoints non supporta i requisiti di sicurezza alternativi (OR logico). Ad esempio, il seguente elenco di requisiti di sicurezza non è supportato:

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

La definizione precedente richiede che un'operazione accetti richieste che seguono i requisiti petstore_auth o i requisiti api_key.

Tuttavia, tieni presente che Cloud Endpoints supporta la combinazione dei requisiti di sicurezza (AND logico). Ad esempio, il seguente elenco di requisiti di sicurezza è supportato:

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

Questa definizione richiede che un'operazione accetti richieste che seguono contemporaneamente i requisiti petstore_auth e i requisiti api_key.

Modelli di percorso dell'URL

Cloud Endpoints supporta solo i parametri dei modelli di percorso dell'URL che corrispondono a segmenti interi del percorso (delimitati da barre "/"). I parametri dei modelli di percorso dell'URL che corrispondono a segmenti parziali del percorso non sono supportati.

Ad esempio, i seguenti modelli di percorso dell'URL sono supportati:

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

I seguenti modelli di percorso dell'URL non sono supportati e verranno rifiutati.

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

Operazioni sul percorso principale dell'URL "/"

Cloud Endpoints accetta documenti OpenAPI che includono operazioni sul percorso principale "/". Tuttavia, le richieste sul percorso principale vengono rifiutate dal proxy ESP (Extensible Service Proxy).

Ad esempio, il seguente snippet di documento OpenAPI è accettato:

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

Le successive richieste di POST /, invece, vengono rifiutate con il seguente errore:

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

Parametri, schemi e tipi

Cloud Endpoints ignora la maggior parte delle definizioni di parametri e tipi.

In particolare, Cloud Endpoints accetta documenti OpenAPI che includono definizioni di parametri e tipi obbligatori, ma tali definizioni non vengono applicate nelle richieste in entrata. Di seguito è riportato un elenco parziale con esempi delle definizioni che Cloud Endpoints accetta ma non applica.

• Parametri dei dati dei moduli, ad esempio:

  parameters:
  - name: avatar
    in: formData
    description: "The avatar of the user"
    type: string

• Parametri obbligatori, ad esempio:

  parameters:
  - name: message
    in: query
    description: "Message to send"
    required: true
    type: string

• Formati di raccolta di array, ad esempio:

  parameters:
  - name: items
    in: query
    description: "List of item IDs"
    required: true
    type: array
    items:
      type: string
    collectionFormat: tsv

• Composizione del tipo, ad esempio:

  definitions:
    base:
      properties:
        message:
          type: string
    extended:
      description: "Extends the base type"
      allOf:
      - $ref: "#/definitions/base"
      - type: object
        properties:
          extension:
            type: string

• Oggetti di risposta diversi per codice di stato, ad esempio:

  responses:
    200:
      description: "Echo"
      schema:
        $ref: "#/definitions/EchoResponse"
    400:
      description: "Error"
      schema:
        type: string

Riferimenti a tipi esterni

Cloud Endpoints non supporta i riferimenti a tipi all'esterno di un documento OpenAPI. Ad esempio, Cloud Endpoints rifiuta i documenti OpenAPI che includono:

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

Bug noti

Documenti OpenAPI rifiutati

Quando distribuisci documenti OpenApi tramite gcloud endpoints services deploy, Cloud Endpoints rifiuta i documenti OpenApi che includono:

• Parametri del corpo di array, ad esempio:

  parameters:
  - name: message
    description: "Message to echo"
    in: body
    schema:
      type: array
      items:
        type: string

Limitazioni della chiave API

Quando specifichi una chiave API nell'oggetto delle definizioni di sicurezza del tuo documento OpenAPI, Cloud Endpoints richiede quanto segue:

• Il campo name deve essere key
• Il campo in deve essere query

Ad esempio:

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

Quando distribuisci un documento OpenAPI con altri tipi di definizioni di sicurezza della chiave API, Cloud Endpoints potrebbe accettarle e generare un avviso. Tuttavia, le definizioni di sicurezza della chiave API vengono ignorate nelle richieste in entrata.