OpenAPI 개요

API 게이트웨이는 OpenAPI 사양 버전 2.0을 사용하여 기술되는 API를 지원합니다. API는 Django 또는 Jersey와 같이 공개적으로 사용 가능한 REST 프레임워크를 사용하여 구현할 수 있습니다.

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

이점

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

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

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

OpenAPI 문서의 기본 구조

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

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

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: DNS_NAME_OF_DEPLOYED_API
    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 및 Node 개발자의 경우 OpenAPI.Tools는 흥미로운 프로젝트일 수 있습니다.

OpenAPI 커뮤니티는 OpenAPI 문서 작성(일부 언어의 경우 자동 생성)에 도움이 되는 도구를 지속적으로 개발하고 있습니다 자세한 내용은 OpenAPI 사양을 참조하세요.

다음 단계