OpenAPI 개요

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 파일을 통해 다음을 확인할 수 있습니다.

OpenAPI 문서 생성

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

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

다음 단계