Cloud Endpoints는 OpenAPI 사양 버전 2.0을 사용하여 설명된 API를 지원합니다.
API는 Django 또는 Jersey와 같이 공개적으로 사용 가능한 REST 프레임워크를 사용하여 구현할 수 있습니다.
API는 OpenAPI 문서라고 하는 JSON 또는 YAML 파일로 설명합니다. 이 페이지에서는 OpenAPI를 사용하여 실현할 수 있는 장점에 대해 설명하고 기본적인 OpenAPI 문서를 보여주며 OpenAPI를 처음 시작하는 데 도움이 되는 추가 정보를 제공합니다.
이점
OpenAPI를 사용하여 얻을 수 있는 주요 장점 중 하나는 문서입니다. API를 설명하는 OpenAPI 문서를 마련하면 API용 참조 문서를 간편하게 생성할 수 있습니다. 자세한 내용은 Cloud Endpoints 포털을 참조하세요.
OpenAPI를 사용하여 얻을 수 있는 다른 장점도 있습니다. 예를 들어 다음이 가능합니다.
- 수십 개의 언어로 클라이언트 라이브러리를 생성합니다.
- 서버 스텁을 생성합니다.
- 프로젝트를 사용하여 적합성을 확인하고 샘플을 생성합니다.
OpenAPI 문서의 기본 구조
OpenAPI 문서는 REST API의 노출 영역을 설명하며 다음과 같은 정보를 정의합니다.
- API의 이름 및 설명
- API의 개별 엔드포인트(경로)
- 호출자를 인증하는 방법
OpenAPI를 처음 사용하는 경우에는 샘플 OpenAPI 문서(Swagger 사양이라고도 부름)를 제공하고 파일의 각 섹션을 간단하게 설명하는 Swagger 기본 구조 웹사이트를 참조하세요. Endpoints 빠른 시작의 OpenAPI 문서에서 이러한 기본 구조를 보여줍니다.
swagger: "2.0"
info:
title: "Airport Codes"
description: "Get the name of an airport from its three-letter IATA code."
version: "1.0.0"
# This field will be replaced by the deploy_api.sh script.
host: "YOUR-PROJECT-ID.appspot.com"
schemes:
- "https"
paths:
"/airportName":
get:
description: "Get the airport name for a given IATA code."
operationId: "airportName"
parameters:
-
name: iataCode
in: query
required: true
type: string
responses:
200:
description: "Success."
schema:
type: string
400:
description: "The IATA code is invalid or missing."
기본 구조 외에 가이드에 사용되는 샘플 코드의 openapi.yaml 파일을 통해 다음을 확인할 수 있습니다.
- API 키를 사용하도록 경로를 구성하는 방법
- 인증을 위한 다양한 보안 체계
- Endpoints API에 사용할 수 있는 OpenAPI 확장 프로그램
OpenAPI 문서 생성
사용하는 언어에 따라 OpenAPI 문서를 생성할 수 있습니다. 자바의 경우 주석에서 OpenAPI 문서를 생성할 수 있도록 Jersey 및 Spring을 위한 오픈소스 프로젝트가 제공됩니다. Maven 플러그인도 있습니다. Python 사용자에게는 flask-swagger 프로젝트가 제공되고 Node 개발자에게는 swagger-node-express가 제공됩니다.
OpenAPI 커뮤니티는 OpenAPI 문서 작성(일부 언어의 경우 자동 생성)에 도움이 되는 도구를 지속적으로 개발하고 있습니다 전체 도구 및 통합 목록은 Swagger 웹사이트를 참조하세요.