Limitazioni delle funzionalità OpenAPI

OpenAPI   | gRPC

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

Le sezioni seguenti descrivono le limitazioni delle funzionalità OpenAPI su Endpoint.

Ambiti ignorati

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

Requisiti di sicurezza multipli

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

Requisiti di sicurezza contenenti una chiave API

ESP non supporta la sicurezza alternativa (OR logico) se uno degli schemi di sicurezza è una chiave API. Ad esempio: ESP non supporta il seguente elenco di requisiti di sicurezza:

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

Questa definizione richiede che un'operazione accetti le richieste che seguono Requisiti di petstore_auth o i requisiti di api_key.

Tieni presente, tuttavia, che ESP supporta i requisiti di sicurezza congiunzioni (AND logico), in modo da poter richiedere sia una chiave API che OAuth2 autenticazione. Ad esempio, è supportato il seguente elenco di requisiti di sicurezza:

security:
- petstore_auth: []
  api_key: []

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

Requisiti di sicurezza per OAuth2

ESP supporta 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 non convalida che tutti i requisiti di sicurezza (tra cui a livello di API o di metodo), sono presenti anche nella sezione Sezione securityDefinitions. Di conseguenza, se la specifica API utilizza un schema di sicurezza indefinito, possono arrivare richieste non autenticate tramite l'API, il livello in cui è configurato il token di sicurezza non definito. Assicurati che tutti i token di sicurezza utilizzati dall'API e i relativi metodi sono definiti nel le definizioni nel 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 oblique /). 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 /

Gli endpoint accettano documenti OpenAPI che includono operazioni su il percorso principale /. Tuttavia, le richieste sul percorso principale vengono rifiutate ESP. Tieni presente che questa limitazione riguarda solo ESP, 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 i valori type: file per il caricamento dei file , al loro posto si deve usare type: string.

Ad esempio, il seguente snippet type: file 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.

Con type: string, invece, è consentito quanto segue:

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 ignora la maggior parte delle definizioni di parametri e tipi.

Gli endpoint accettano documenti OpenAPI che includono requisiti definizioni di parametri e tipi, ma ESP non le applica le definizioni e inoltra le richieste in entrata all'API. Di seguito è riportato un elenco parziale che fornisce esempi di definizioni non applicate da ESP:

• 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 OpenAPI documenti che includono:

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

Porta personalizzata nell'indirizzo host del servizio

Gli endpoint non consentono l'utilizzo di porte personalizzate nel campo host di un documento OpenAPI. Ad esempio, Endpoints rifiuta OpenAPI documenti 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'API OpenAPI sono presenti più di 200 alias YAML di riferimento, consigliamo di rimuovere gli alias di riferimento ove possibile per rispettare questo limite.

Bug noti

Documenti OpenAPI rifiutati

Quando esegui il deployment del tuo documento OpenAPI utilizzando gcloud endpoints services deploy, Endpoint 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 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 per la definizione delle chiavi API

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

• Il name è key e il in è query
• Il valore name è api_key e il valore in è query
• Il name è x-api-key e il 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 sicurezza delle chiavi API le definizioni, Endpoints potrebbe accettarle e restituire un avviso. Tuttavia, le definizioni di sicurezza della chiave API vengono ignorate nelle richieste in entrata.

Il portale Cloud Endpoints non esegue il rendering dei tipi di composizione

Sebbene Endpoints accetti documenti OpenAPI con composizione ovvero digita allOf nella definizione, Il portale Endpoints non genera documentazione per tipi di composizione.