Limitazioni delle funzionalità OpenAPI

OpenAPI | gRPC

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

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

Ambiti ignorati

Anche se Endpoints accetta documenti OpenAPI con ambiti definiti in un oggetto schema di sicurezza, quando viene inviata una richiesta all'API, né l'Extensible Service Proxy (ESP) né il Cloud Endpoints Frameworks controllano gli ambiti definiti.

Più requisiti di sicurezza

Puoi specificare più di un requisito di sicurezza nel documento OpenAPI. In questa sezione vengono descritti gli schemi di sicurezza supportati da ESP.

Requisiti di sicurezza contenenti una chiave API

ESP non supporta i requisiti di sicurezza alternativi (logici O) quando 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 un'operazione per accettare richieste che rispettano i requisiti petstore_auth o i requisiti api_key.

Tieni presente, tuttavia, che ESP supporta le congiunzioni relative ai requisiti di sicurezza (AND logico), quindi è possibile richiedere sia una chiave API sia l'autenticazione OAuth2. Ad esempio, il seguente elenco di requisiti di sicurezza è supportato:

security:
- petstore_auth: []
  api_key: []

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

Requisiti di sicurezza per OAuth2

ESP supporta i requisiti di sicurezza alternativi per la sicurezza (OR), ma solo per gli schemi di sicurezza dell'autenticazione OAuth2. Ad esempio, è supportato il seguente elenco di requisiti di sicurezza:

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

Convalida definizioni di sicurezza

ESP non convalida 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 provenire dall'API, a livello di configurazione del token di sicurezza non definito. Assicurati che tutti i token di sicurezza utilizzati dalla tua API e i relativi metodi siano definiti nelle definizioni di sicurezza del tuo documento OpenAPI.

Modelli del percorso dell'URL

Gli endpoint supportano solo i parametri del modello di percorso dell'URL che corrispondono a segmenti interi del percorso (delimitati da barre /). I parametri del modello di percorso del percorso che corrispondono a segmenti del percorso parziale non sono supportati.

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

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

I seguenti modelli di percorsi degli 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 relative al percorso principale vengono rifiutate da 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

Le richieste successive per 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."
}

Caricamento file

Gli endpoint non accettano type: file per i parametri di caricamento del file, pertanto è necessario utilizzare 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 è 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.

Endpoints accetta i documenti OpenAPI che includono le definizioni dei parametri e dei tipi richiesti, ma ESP non applica queste definizioni e inoltra le richieste in entrata alla tua API. Di seguito è riportato un elenco parziale che fornisce esempi delle 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 a 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 dell'host di servizio

Endpoints non consente le 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

Bug noti

Documenti OpenAPI rifiutati

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

• I 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 relative alla definizione delle chiavi API

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

• name è key e in è query
• name è api_key e in è query
• name è x-api-key e 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, gli endpoint potrebbero accettarle e generare un avviso. Tuttavia, le definizioni di sicurezza della chiave API vengono ignorate nelle richieste in entrata.

I tipi di composizione non vengono visualizzati nel portale Cloud Endpoints

Anche se Endpoints accetta documenti OpenAPI con tipi di composizione, ovvero tipi con allOf nella definizione, il portale degli endpoint non genera la documentazione per i tipi di composizione.