Limitazioni delle funzionalità di OpenAPI

OpenAPI   |  gRPC

Cloud Endpoints accetta solo la versione 2 della specifica OpenAPI.

Le sezioni seguenti descrivono le limitazioni delle funzionalità OpenAPI negli endpoint.

Ambiti ignorati

Sebbene Endpoints accetti documenti OpenAPI con ambiti definiti in un oggetto schema di sicurezza, quando viene inviata una richiesta all'API, né Extensible Service Proxy (ESP), né Extensible Service Proxy V2 (ESPv2) né Cloud Endpoints Frameworks controllano gli ambiti definiti.

Più requisiti di sicurezza

Puoi specificare più di un requisito di sicurezza nel documento OpenAPI. Questa sezione descrive gli schemi di sicurezza supportati da ESP ed ESPv2.

Requisiti di sicurezza contenenti una chiave API

ESP ed ESPv2 non supportano i requisiti di sicurezza alternativi (OR logico) quando uno degli schemi di sicurezza è una chiave API. Ad esempio, ESP ed ESPv2 non supportano il seguente elenco di requisiti di sicurezza:

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

Questa definizione richiede un'operazione per accettare richieste che rispettano i requisiti petstore_auth o api_key.

Tieni presente, tuttavia, che ESP ed ESPv2 supportano le connessioni dei requisiti di sicurezza (AND logico), quindi puoi richiedere sia una chiave API sia l'autenticazione OAuth2. Ad esempio, è supportato il seguente elenco di requisiti di sicurezza:

security:
- petstore_auth: []
  api_key: []

Questa definizione richiede un'operazione per accettare richieste che rispettino contemporaneamente i requisiti petstore_auth e api_key.

Requisiti di sicurezza per OAuth2

ESP ed ESPv2 supportano i requisiti di sicurezza alternativi (OR logico), ma solo per i schemi di sicurezza di autenticazione OAuth2. Ad esempio, è supportato il seguente elenco di requisiti di sicurezza:

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

Convalida della definizione di sicurezza

ESP ed ESPv2 non convalidano che tutti i requisiti di sicurezza (a livello di API o di metodo) siano presenti anche nella sezione securityDefinitions. Di conseguenza, se la specifica dell'API utilizza uno schema di sicurezza non definito, le richieste non autenticate potrebbero essere inviate tramite l'API, al livello in cui è configurata la chiave di sicurezza non definita. Assicurati che tutte le chiavi di sicurezza utilizzate dall'API e dai relativi metodi siano definite nelle definizioni di sicurezza del documento OpenAPI.

Modelli di percorso dell'URL

Gli endpoint supportano solo i parametri del modello di percorso dell'URL che corrispondono a interi segmenti di percorso (delimitati da barre /). I parametri del modello di percorso dell'URL che corrispondono a segmenti di percorso parziali 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 /

Endpoints accetta documenti OpenAPI che includono operazioni sul percorso principale /. Tuttavia, le richieste sul percorso principale vengono rifiutate dall'ESP. Tieni presente che questa limitazione riguarda solo ESP, mentre ESPv2 supporta il percorso principale /.

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

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

Tuttavia, le richieste successive di POST / 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."
}

Caricamento file

Gli endpoint non accettano il parametro type: file per il caricamento dei file, ma è necessario utilizzare type: string.

Ad esempio, lo snippet type: file seguente non è consentito:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: file
          description: The file to upload.

Mentre è consentito quanto segue con type: string:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: string
          description: The file to upload.

Parametri, schemi e tipi

ESP ed ESPv2 ignorano la maggior parte delle definizioni di parametri e tipi.

Endpoints accetta documenti OpenAPI che includono parametri obbligatori e definizioni di tipo, ma ESP ed ESPv2 non applicano queste definizioni e inoltrano le richieste in arrivo alla tua API. Di seguito è riportato un elenco parziale che fornisce esempi di definizioni non applicate da ESP ed ESPv2:

• 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

Endpoints non supporta i riferimenti ai tipi esterni a un documento OpenAPI. Ad esempio, Endpoints rifiuta i documenti OpenAPI che includono:

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

Porta personalizzata nell'indirizzo host del servizio

Endpoints non consente porte personalizzate nel campo host di un documento OpenAPI. Ad esempio, Endpoints rifiuta i documenti OpenAPI come:

swagger: 2.0
host: example.com:8080
schemes:
- http

Limitazioni degli alias YAML

Gli endpoint possono supportare fino a 200 nodi alias YAML in un documento OpenAPI. Se in un documento OpenAPI sono presenti più di 200 alias YAML, ti consigliamo di dereferenziare gli alias, ove possibile, per rispettare questo limite.

Bug noti

Documenti OpenAPI rifiutati

Quando esegui il deployment del documento OpenAPI utilizzando gcloud endpoints services deploy, 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

• Percorsi con barre oblique finali, ad esempio:

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

  Per risolvere il problema, rimuovi la barra finale da /echo/:

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

Limitazioni alla definizione delle chiavi API

Quando specifichi una chiave API nell'oggetto definizioni di sicurezza del tuo documento OpenAPI, Endpoints richiede uno dei seguenti schemi:

• Il valore name è key e il valore in è query
• Il valore name è api_key e il valore in è query
• Il valore name è x-api-key e il valore in è header

Ad esempio:

"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"
    },
}

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