OpenAPI 기능 제한사항

OpenAPI | gRPC

현재 Cloud Endpoints는 OpenAPI 사양 버전 2만 허용합니다.

아래 섹션에서는 Endpoints의 OpenAPI 기능 제한사항을 설명합니다.

무시하는 범위

Endpoints는 범위가 보안 스키마 객체에 정의된 OpenAPI 문서를 수락하지만 API에 요청이 전송될 때 Extensible Service Proxy(ESP)와 Cloud Endpoints Frameworks는 정의된 범위를 확인하지 않습니다.

여러 보안 요구사항

OpenAPI 문서에서 여러 개의 보안 요구사항을 지정할 수 있습니다. 이 섹션에서는 ESP가 지원하는 보안 스키마에 대해 설명합니다.

API 키를 포함하는 보안 요구사항

ESP는 보안 체계 중 하나가 API 키일 때 대체(논리합) 보안 요구사항을 지원하지 않습니다. 예를 들어 ESP는 다음 보안 요구사항 목록을 지원하지 않습니다.

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

이 정의에서는 작업이 petstore_auth 요구사항이나 api_key 요구 사항을 따르는 요청을 허용해야 합니다.

그러나 ESP는 보안 요구사항 결합(논리곱)을 지원하므로 API 및 OAuth2 인증을 모두 요구할 수 있습니다. 예를 들어 다음 보안 요구사항 목록이 지원됩니다.

security:
- petstore_auth: []
  api_key: []

이 정의에서는 작업이 petstore_auth 요구사항과 api_key 요구사항을 동시에 따르는 요청을 허용해야 합니다.

OAuth2의 보안 요구사항

ESP는 보안 대체(논리합) 보안 요구사항을 지원하지만 OAuth2 인증 보안 체계에 대해서만 지원합니다. 예를 들어 다음 보안 요구사항 목록이 지원됩니다.

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

보안 정의 유효성 검사

ESP는 모든 보안 요구사항(API 수준 또는 메서드 수준에서)이 securityDefinitions 섹션에 있는지 검증하지 않습니다. 따라서 API 사양에서 정의되지 않은 보안 스키마를 사용하는 경우 정의되지 않은 보안 키가 구성된 수준에서 API를 통해 인증되지 않은 요청이 발생할 수 있습니다. API에서 사용하는 모든 보안 키와 해당 메서드는 OpenAPI 문서의 보안 정의에 정의되어 있는지 확인합니다.

URL 경로 템플릿

Endpoints는 슬래시(//)로 구분된 전체 경로 세그먼트에 해당하는 URL 경로 템플릿 매개변수만 지원합니다. 부분적 경로 세그먼트에 해당하는 URL 경로 템플릿 매개변수는 지원되지 않습니다.

예를 들어 다음 URL 경로 템플릿이 지원됩니다.

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

다음 URL 경로 템플릿은 지원되지 않고 거부됩니다.

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

URL 루트 경로 /에서의 작업

Endpoints는 루트 경로 /에서의 작업이 포함된 OpenAPI 문서를 허용합니다. 그러나 루트 경로에서의 요청은 ESP에서 거부됩니다. 이 제한은 ESP에만 해당되며 ESPv2는 루트 경로 /를 지원합니다.

예를 들어 다음 OpenAPI 문서 스니펫이 허용됩니다.

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

그러나 POST /에 대한 후속 요청은 다음 오류와 함께 거부됩니다.

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

파일 업로드

Endpoints에서는 파일 업로드 매개변수로 type: file이 사용되지 않습니다. 대신 type: string이 사용됩니다.

예를 들어 다음 type: file 스니펫은 허용되지 않습니다.

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

반면에 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.

매개변수, 스키마, 유형

ESP는 대부분의 매개변수 및 유형 정의를 무시합니다.

Endpoints는 필수 매개변수 및 유형 정의가 포함된 OpenAPI 문서를 수락하지만 ESP는 이러한 정의를 강제하지 않으며 수신 요청을 API로 전달합니다. 다음은 ESP가 강제하지 않는 정의의 예를 제공하는 부분적인 목록입니다.

• 양식 데이터 매개변수

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

• 필수 매개변수

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

• 배열 컬렉션 형식

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

• 유형 구성

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

• 상태 코드별로 다른 응답 개체

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

외부 유형 참조

Endpoints는 OpenAPI 문서 외부의 유형에 대한 참조를 지원하지 않습니다. 예를 들어 Endpoints는 다음이 포함된 OpenAPI 문서를 거부합니다.

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

서비스 호스트 주소의 커스텀 포트

Endpoints는 OpenAPI 문서의 host 필드에 커스텀 포트를 허용하지 않습니다. 예를 들어 Endpoints는 다음과 같은 OpenAPI 문서를 거부합니다.

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

YAML 별칭 제한사항

Endpoints는 OpenAPI 문서에서 최대 200개의 YAML 별칭 노드를 지원할 수 있습니다. OpenAPI 문서에 YAML 별칭이 200개 넘게 있으면 가능한 경우 이 제한을 준수하여 별칭을 참조하지 않는 것이 좋습니다.

알려진 버그

OpenAPI 문서 거부

gcloud endpoints services deploy를 사용하여 OpenAPI 문서를 배포하면 Endpoints는 다음을 포함하는 OpenAPI 문서를 거부합니다.

• 배열 본문 매개변수

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

• 백슬래시가 있는 경로. 예:

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

  이 문제를 해결하려면 /echo/에서 후행 슬래시를 삭제합니다.

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

API 키 정의 제한사항

OpenAPI 문서의 보안 정의 객체에서 API 키를 지정할 때는 Endpoints에 다음 스키마 중 하나가 필요합니다.

• name은 key이고 in은 query입니다.
• name은 api_key이고 in은 query입니다.
• name은 x-api-key이고 in은 header입니다.

예를 들면 다음과 같습니다.

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

다른 유형의 API 키 보안 정의로 OpenAPI 문서를 배포하면 Endpoints가 수락한 후 경고를 출력할 수 있습니다. 하지만 수신 요청에서는 API 키 보안 정의가 무시됩니다.

Cloud Endpoints 포털에서 합성 유형을 렌더링하지 않음

Endpoints는 composition 유형의 OpenAPI 문서를 허용하지만 정의에 allOf가 포함된 유형은 Endpoints Portal에서 composition 유형에 대한 문서를 생성하지 않습니다.