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.