OpenAPI 개요

Cloud Endpoints는 OpenAPI 사양의 지원되는 버전을 사용하여 설명된 API를 지원합니다.

API는 Django 또는 Jersey와 같이 공개적으로 사용 가능한 REST 프레임워크를 사용하여 구현할 수 있습니다.

API는 OpenAPI 문서라고 하는 JSON 또는 YAML 파일로 설명합니다. 이 페이지에서는 OpenAPI를 사용하여 실현할 수 있는 장점에 대해 설명하고 기본적인 OpenAPI 문서를 보여주며 OpenAPI를 처음 시작하는 데 도움이 되는 추가 정보를 제공합니다.

지원되는 OpenAPI 버전

Cloud Endpoints는 다음 OpenAPI 버전을 지원합니다.

  1. OpenAPI 2.0 (이전 명칭: Swagger)
  2. OpenAPI 3.0.x

각 버전의 공식 사양은 OpenAPI 이니셔티브에서 확인할 수 있습니다.

패치 버전 지원

OpenAPI 사양에 따르면 패치 버전 (예: 3.0.1, 3.0.2)은 수정사항이나 설명만 도입하고 새로운 기능을 추가하지 않습니다. 따라서 Cloud Endpoints는 3.0의 모든 패치 버전을 지원합니다.

용어

Cloud Endpoints 문서에서 OpenAPI 3.x는 지원되는 모든 OpenAPI 3 버전을 의미합니다.

이점

OpenAPI를 사용할 때 중요한 이점 중 하나는 문서입니다. API를 설명하는 OpenAPI 문서가 있으면 API에 대해 참조 문서를 생성할 수 있습니다.

OpenAPI를 사용하여 얻을 수 있는 다른 장점도 있습니다. 예를 들어 다음이 가능합니다.

  • 수십 개의 언어로 클라이언트 라이브러리를 생성합니다.
  • 서버 스텁을 생성합니다.
  • 프로젝트를 사용하여 적합성을 확인하고 샘플을 생성합니다.

OpenAPI 문서의 기본 구조

OpenAPI 문서는 REST API의 노출 영역을 설명하며 다음과 같은 정보를 정의합니다.

  • API의 이름 및 설명
  • API의 개별 엔드포인트(경로)
  • 호출자를 인증하는 방법

OpenAPI 문서의 구조는 사용하는 OpenAPI 버전에 따라 다릅니다. 다음 예에서는 OpenAPI 2.0 및 OpenAPI 3.x의 구조를 설명합니다.

OpenAPI 2.0

OpenAPI를 처음 사용하는 경우에는 샘플 OpenAPI 문서(Swagger 사양이라고도 부름)를 제공하고 파일의 각 섹션을 간단하게 설명하는 Swagger 기본 구조 웹사이트를 참조하세요. 다음 예시는 이러한 기본 구조를 보여줍니다.

swagger: "2.0"
info:
  title: API_ID optional-string
  description: "Get the name of an airport from its three-letter IATA code."
  version: "1.0.0"
host: API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
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 3.x

OpenAPI를 처음 사용하는 경우에는 샘플 OpenAPI 문서를 제공하고 파일의 각 섹션을 설명하는 OpenAPI 사양을 참고하세요.

다음 예시는 이러한 기본 구조를 보여줍니다.

openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Get the name of an airport from its three-letter IATA code
  version: 1.0.0
servers:
  - url: https://API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}
x-google-api-management:
  backend:
    BACKEND_NAME
      address: https://BACKEND_URL/airportNameGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
x-google-backend: BACKEND_NAME
paths:
  /airportName:
    get:
      summary: Get the airport name for a given IATA code
      operationId: airportName
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
      parameters:
        - name: iataCode
          in: query
          required: true
          schema:
            type: string

기본 구조 외에 가이드에 사용되는 샘플 코드의 openapi.yaml 파일을 통해 다음을 확인할 수 있습니다.

OpenAPI 문서 생성

사용하는 언어에 따라 OpenAPI 문서를 생성할 수 있습니다. 자바의 경우 주석에서 OpenAPI 문서를 생성할 수 있도록 Jersey 및 Spring을 위한 오픈소스 프로젝트가 제공됩니다. Maven 플러그인도 있습니다. Python 사용자에게는 flask-swagger 프로젝트가 제공되고 Node 개발자에게는 swagger-node-express가 제공됩니다.

OpenAPI 커뮤니티는 OpenAPI 문서 작성(일부 언어의 경우 자동 생성)에 도움이 되는 도구를 지속적으로 개발하고 있습니다 전체 도구 및 통합 목록은 Swagger 웹사이트를 참조하세요.

다음 단계