[GPT Actions] 1. OpenAPI 스키마 기본 구조 이해하기
안녕하세요! 오늘은 OpenAPI 스키마의 기본 구조에 대해 알아보겠습니다. OpenAPI 스키마는 API를 설계하고 문서화하는 데 사용되는 표준 형식입니다. 코딩 경험이 없으신 분들도 걱정 마세요. 천천히 따라오시면 됩니다.
OpenAPI 스키마란? OpenAPI 스키마는 API의 구조와 기능을 설명하는 문서입니다. 이를 통해 개발자들은 API를 쉽게 이해하고 사용할 수 있습니다. 마치 레고 설명서와 같다고 생각하시면 됩니다!
기본 구조 살펴보기 OpenAPI 스키마는 여러 부분으로 구성되어 있습니다. 주요 부분을 하나씩 살펴볼까요?
a. openapi: 이는 사용하는 OpenAPI 스키마의 버전을 나타냅니다. 우리는 최신 버전인 3.1.0을 사용할 거예요.
b. info: API에 대한 기본 정보를 제공합니다. 제목, 설명, 버전 등이 포함됩니다.
c. servers: API 서버의 URL을 지정합니다. API가 호스팅되는 곳이라고 생각하시면 됩니다.
d. paths: API의 각 경로(endpoint)와 해당 경로에서 수행할 수 있는 작업을 정의합니다.
e. components: 재사용 가능한 스키마 요소들을 정의합니다. 여러 곳에서 사용되는 공통 부분을 여기에 저장해둡니다.
실습: 기본 구조 작성하기 자, 이제 직접 기본 구조를 작성해볼까요? 아래 단계를 따라해보세요.
Step 1: 새 텍스트 파일을 만들고 'my_api.yaml'이라고 이름 붙여주세요.
Step 2: 파일을 열고 다음 내용을 입력해주세요:
openapi: 3.1.0 info: title: My First API description: This is a simple API to learn OpenAPI version: 1.0.0 servers: - url: https://api.example.com/v1 paths: components: schemas:각 부분 설명
openapi: 3.1.0 : 우리가 사용하는 OpenAPI 스키마의 버전입니다.
info: API에 대한 기본 정보를 제공합니다.
title: API의 이름입니다.
description: API에 대한 간단한 설명입니다.
version: API의 버전을 나타냅니다.
servers: API 서버의 URL을 지정합니다. 여기서는 예시 URL을 사용했습니다.
paths: 여기에 API의 경로들을 정의할 것입니다. 지금은 비어있습니다.
components: 재사용 가능한 스키마 요소들을 정의할 곳입니다. 역시 지금은 비어있습니다.
YAML 형식 이해하기 OpenAPI 스키마는 주로 YAML 형식으로 작성됩니다. YAML은 데이터를 표현하는 간단한 형식입니다.
들여쓰기가 중요합니다. 들여쓰기로 데이터의 계층 구조를 나타냅니다.
콜론(:) 뒤에 오는 공백도 중요합니다. 항상 콜론 뒤에 공백을 넣어주세요.
하이픈(-)은 목록을 나타낼 때 사용합니다.
[연습문제] 방금 작성한 기본 구조를 바탕으로 다음 정보를 추가해보세요:
API 제목을 "My Awesome Bookstore API"로 변경해보세요.
설명을 "This API provides access to our bookstore's inventory and order system"으로 수정해보세요.
API 버전을 2.0.0으로 업데이트해보세요.
서버 URL을 "https://bookstore.api.example.com/v2"로 변경해보세요.
힌트: info 섹션과 servers 섹션을 수정하면 됩니다!
[정답] 여러분의 파일이 이렇게 보인다면 정답입니다:
openapi: 3.1.0
info:
title: My Awesome Bookstore API
description: This API provides access to our bookstore's inventory and order system
version: 2.0.0
servers:
- url: https://bookstore.api.example.com/v2
paths:
components:
schemas:축하합니다! 여러분은 방금 첫 번째 OpenAPI 스키마의 기본 구조를 작성하셨습니다. 이것이 모든 API 설계의 시작점이 됩니다.
이번 파트에서는 OpenAPI 스키마의 기본 구조에 대해 배웠습니다. 우리는 openapi, info, servers, paths, components라는 주요 섹션에 대해 알아보았고, 간단한 예제를 작성해보았습니다.
다음 파트에서는 paths 섹션을 더 자세히 살펴보고, 실제 API 경로를 정의하는 방법에 대해 배워보겠습니다. API 설계의 세계로 첫 발을 내딛으신 것을 축하드립니다!
질문이나 궁금한 점이 있다면 언제든 물어보세요. 다음 파트에서 만나요!
