이 페이지는 Cloud Translation API를 통해 번역되었습니다.

OpenAPI 3.x를 사용하도록 게이트웨이 수정

이 페이지에서는 API 구성에 OpenAPI 3.x 사양을 사용하도록 기존 API 게이트웨이를 수정하는 방법을 설명합니다.

시작하기 전에

OpenAPI 2.0 사양으로 구성된 기존 API 게이트웨이 인스턴스가 있는지 확인합니다.
gcloud CLI 설치 자세한 내용은 Google Cloud CLI 설치를 참고하세요.

OpenAPI 3.x를 사용하도록 API 구성 수정

OpenAPI 3.x를 사용하도록 기존 OpenAPI 2.0 API 게이트웨이 구성을 수정하려면 다음 단계를 완료하세요.

현재 API 구성 찾기

게이트웨이와 연결된 API 구성을 찾습니다.

API 게이트웨이 인스턴스를 설명합니다.

gcloud api-gateway gateways describe GATEWAY_ID --project=PROJECT_ID --location=GATEWAY_LOCATION

다음을 바꿉니다.

GATEWAY_ID: 게이트웨이의 ID입니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
GATEWAY_LOCATION: 게이트웨이의 위치입니다.

출력에 apiConfig 경로가 표시됩니다. 예를 들면 다음과 같습니다.

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-gateway-config
createTime: '2025-03-25T02:49:58.641650649Z'
defaultHostname: my-gateway-a1b2c3d4.uc.gateway.dev
displayName: My gateway
name: projects/my-project/locations/us-west1/gateways/my-new-gateway
state: ACTIVE
updateTime: '2025-03-25T02:51:52.674308428Z'

OpenAPI 문서 가져오기

확인한 API 구성의 OpenAPI 문서를 가져오려면 다음 단계를 따르세요.

API 구성을 설명합니다.

gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID --project=PROJECT_ID --view=FULL

다음을 바꿉니다.

CONFIG_ID: API 구성의 ID입니다.
API_ID: API의 ID입니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

출력에 OpenAPI 문서의 base64 인코딩 콘텐츠가 포함된 openapiDocuments 섹션이 표시됩니다.

createTime: '2024-02-16T21:11:36.293169474Z'
displayName: my-api-config
gatewayServiceAccount: projects/-/serviceAccounts/api-gateway-sa@my-sandbox.iam.gserviceaccount.com
name: projects/my-project-id/locations/global/apis/my-api/configs/my-gateway-config
openapiDocuments:
-   document:
    contents: IyBvc...
    path: apigateway-config.yaml
serviceConfigId: my-api-config-0a1fjkfeb7t8z
state: ACTIVE
updateTime: '2024-02-16T21:13:45.626771120Z'

OpenAPI 문서 디코딩

base64로 인코딩된 OpenAPI 문서 콘텐츠를 디코딩하려면 다음 단계를 따르세요.

contents 값을 디코딩합니다.
```
echo 'IyBvc...' | base64 -d
```
IyBvc...을 이전 단계의 실제 contents 값으로 바꿉니다.

출력에 OpenAPI 2.0 문서가 표시됩니다. 예를 들면 다음과 같습니다.
```
swagger: '2.0'
info:
  title: API_ID
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
```

OpenAPI 문서를 OpenAPI 3.x로 변환

도구를 사용하여 OpenAPI 2.0 문서를 OpenAPI 3.x로 변환할 수 있습니다. 예를 들어 Swagger Editor는 변환 유틸리티를 제공합니다.

OpenAPI 3.x로 초기 변환한 후 OpenAPI 3.x에 맞게 문서를 수동으로 추가 변경하여 API Gateway 확장 프로그램 및 기능과의 호환성을 보장합니다. API 게이트웨이에서 지원되는 OpenAPI 3.x 확장 프로그램에 대한 자세한 내용은 API 게이트웨이의 OpenAPI 3.x 확장 프로그램을 참고하세요.

다음 표에는 필요한 변경사항이 설명되어 있습니다.

기능	OpenAPI 2.0	OpenAPI 3.x	변경사항 설명
API 키	`securityDefinitions`	`securitySchemes`	API 키는 기본 OpenAPI API 키 지원을 사용합니다. 변환 도구는 일반적으로 이 작업을 자동으로 처리합니다. 수동으로 변경할 필요가 없습니다.
JWT 인증	`x-google-audiences` 등	`x-google-auth`	OpenAPI 2.0 확장 프로그램에서는 `securityDefinition` 인스턴스에서 개별 확장 프로그램을 사용하여 OAuth 구성을 정의합니다. 변환 도구는 보안 스키마 인스턴스를 `#/components/securitySchemes`로 변환하고 확장 프로그램을 그대로 둡니다. 이러한 확장 프로그램을 `x-google-auth`의 하위 요소가 되도록 수동으로 수정하고 `x-google-` 접두사를 삭제합니다. 값은 동일하게 유지됩니다.
할당량	`x-google-management`, `x-google-quota`	`x-google-api-management`, `x-google-quota`	OpenAPI 2.0 확장 프로그램에서는 `x-google-management`에서 측정항목과 할당량을 정의하고 `x-google-quota`로 연결합니다. 변환 도구는 이러한 확장 프로그램을 그대로 둡니다. 측정항목 및 할당량 구성을 `x-google-management`에서 `x-google-api-management`로 수동으로 이동합니다. YAML 키를 사용하도록 구성을 변경하고 `valueType`, `metricKind`, `unit`를 삭제합니다. `x-google-quota` 인스턴스에서 `metricCosts`를 삭제합니다.
백엔드	`x-google-backend`	`x-google-api-management`, `x-google-backend`	OpenAPI 2.0 확장 프로그램에서 `x-google-backend`에 백엔드를 정의하면 정의된 위치에 구성이 적용됩니다. OpenAPI 3.x 확장 프로그램에서는 `x-google-api-management`에서 백엔드를 정의한 다음 `x-google-backend`로 적용합니다. 변환 도구는 이 확장 프로그램을 그대로 둡니다. 구성을 `x-google-api-management`로 수동으로 이동합니다. `x-google-backend` 인스턴스를 수정하여 해당 구성을 참조합니다.
엔드포인트	`x-google-endpoints`	`x-google-endpoint`, `servers`	OpenAPI 2.0 확장 프로그램에서 `x-google-endpoints`에 엔드포인트 구성을 정의합니다. OpenAPI 3.x 확장 프로그램에서는 `x-google-endpoint`를 사용하지만 루트가 아닌 `servers`의 확장 프로그램입니다. 변환 도구는 이 확장 프로그램을 그대로 둡니다. 이를 `servers`로 수동으로 이동하고 `name` 필드를 삭제합니다. 예를 들면 다음과 같습니다. # OpenAPI 2.0 x-google-endpoints: - name: "my-api.apigateway.my-project.cloud.goog" allowCors: True # OpenAPI 3.0.x servers: - url: https://my-api.apigateway.my-project.cloud.goog/ x-google-endpoint: allowCors: True
API 이름	`x-google-api-name`	`x-google-api-management`	OpenAPI 2.0 확장 프로그램에서는 `x-google-api-name`에 API 이름을 정의합니다. OpenAPI 3.x 확장 프로그램에서는 `x-google-api-management`의 `apiName` 필드를 사용합니다. 이 구성을 `x-google-api-management`로 수동으로 이동합니다.
모든 트래픽 허용	`x-google-allow`	지원되지 않음	OpenAPI 문서에서 이를 삭제합니다. API 게이트웨이는 OpenAPI 3.x에서 이를 지원하지 않습니다.

새 API 구성 만들기

수정된 OpenAPI 3.x 문서를 사용하여 새 API 구성을 만듭니다.

API 구성을 만듭니다.
```
gcloud api-gateway api-configs create NEW_CONFIG_ID --api=API_ID --project=PROJECT_ID --openapi-spec=NEW_API_DEFINITION
```
다음을 바꿉니다.
- NEW_CONFIG_ID: API 구성의 새 ID입니다.
- API_ID: API의 ID입니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- NEW_API_DEFINITION: OpenAPI 3.x 사양 파일의 경로입니다.

게이트웨이 업데이트

수정된 OpenAPI 3.x 문서에서 새 API 구성을 참조하도록 게이트웨이 인스턴스를 업데이트합니다.

게이트웨이를 업데이트합니다.
```
gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION
```
다음을 바꿉니다.
- GATEWAY_ID: 게이트웨이의 ID입니다.
- API_CONFIG: 새 API 구성의 전체 리소스 경로입니다(예: projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID).
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- GATEWAY_LOCATION: 게이트웨이의 위치입니다.

다음 단계

API 게이트웨이에 대해 자세히 알아보세요.
OpenAPI 사양을 살펴봅니다.