[GPT Actions] 2. API 경로(Paths) 및 작업(Operations) 정의하기

달의이성2024-07-19 20:13

안녕하세요! 이번 파트에서는 OpenAPI 스키마의 핵심인 paths 섹션에 대해 자세히 알아보겠습니다. API 경로를 정의하고 각 경로에서 수행할 수 있는 작업을 설명하는 방법을 배워보겠습니다.

paths 섹션이란?

paths 섹션은 API의 모든 엔드포인트(endpoint)와 그에 대한 작업을 정의하는 곳입니다. 엔드포인트란 API에서 특정 리소스나 기능에 접근할 수 있는 URL을 말합니다. 예를 들어, '/books'라는 엔드포인트는 책 정보와 관련된 기능을 제공할 수 있습니다.

HTTP 메서드 이해하기

API에서는 다양한 HTTP 메서드를 사용하여 작업을 수행합니다. 주요 메서드는 다음과 같습니다:

GET: 데이터를 조회할 때 사용
POST: 새로운 데이터를 생성할 때 사용
PUT: 기존 데이터를 전체적으로 수정할 때 사용
PATCH: 기존 데이터의 일부를 수정할 때 사용
DELETE: 데이터를 삭제할 때 사용

기본 경로 정의하기

자, 이제 우리의 Bookstore API에 첫 번째 경로를 추가해볼까요? '/books' 경로를 추가하고, 이 경로에서 GET 요청을 처리하도록 해보겠습니다.

my_api.yaml 파일을 열고 paths 섹션을 다음과 같이 수정해주세요:

paths:
  /books:
    get:
      summary: List all books
      description: Retrieves a list of all books in the inventory
      responses:
        '200':
          description: Successful response
          content:
            application/json:    
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string
                    author:
                      type: string

이 코드가 의미하는 바를 하나씩 살펴보겠습니다:

/books: 이는 우리 API의 엔드포인트입니다. 모든 책 정보에 접근하는 URL이 됩니다.
get: 이 엔드포인트에서 GET 요청을 처리한다는 의미입니다.
summary와 description: 이 작업에 대한 간단한 설명입니다.
responses: 이 작업에 대한 가능한 응답을 정의합니다.
- '200': HTTP 상태 코드 200(성공)에 대한 응답을 정의합니다.
- content: 응답 본문의 내용을 정의합니다.
- schema: 응답 데이터의 구조를 정의합니다.
  - type: array는 응답이 여러 개의 항목으로 이루어진 배열임을 나타냅니다.
  - items: 배열의 각 항목에 대한 정의입니다.
    - properties: 각 책 객체의 속성들을 정의합니다 (id, title, author).

다른 HTTP 메서드 추가하기

이제 같은 '/books' 경로에 POST 메서드를 추가해 새로운 책을 생성하는 기능을 추가해봅시다.

paths:
  /books:
    get:
      # (이전 GET 메서드 정의는 그대로 둡니다)
    post:
      summary: Add a new book
      description: Adds a new book to the inventory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                author:
                  type: string
              required:
                - title
                - author
      responses:
        '201':
          description: Book created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  title:
                    type: string
                  author:
                    type: string

이 POST 메서드 정의에 대해 설명드리겠습니다:

post: 이 엔드포인트에서 POST 요청을 처리한다는 의미입니다.
requestBody: 요청 본문에 대한 정의입니다. 새 책을 추가할 때 필요한 정보를 여기에 포함합니다.
- required: true는 요청 본문이 반드시 필요하다는 의미입니다.
- schema: 요청 본문의 구조를 정의합니다.
  - properties: 요청에 포함될 속성들 (title, author)을 정의합니다.
  - required: 반드시 포함되어야 하는 속성들을 명시합니다.
responses:
- '201': HTTP 상태 코드 201(생성됨)에 대한 응답을 정의합니다.

경로 매개변수 사용하기

때로는 URL의 일부를 변수로 사용해야 할 때가 있습니다. 예를 들어, 특정 ID의 책 정보를 가져오고 싶다면 어떻게 해야 할까요? 이럴 때 경로 매개변수를 사용합니다.

'/books/{bookId}' 경로를 추가해 봅시다:

paths:
  /books:
    # (이전 /books 경로 정의는 그대로 둡니다)
  /books/{bookId}:
    get:
      summary: Get a book by ID
      description: Retrieves details of a specific book
      parameters:
        - name: bookId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  title:
                    type: string
                  author:
                    type: string
        '404':
          description: Book not found

/books/{bookId}: {bookId}는 경로 매개변수입니다. 실제 요청에서는 이 부분에 특정 ID 값이 들어갑니다.
parameters:
- name: bookId는 매개변수의 이름입니다.
- in: path는 이 매개변수가 URL 경로에 있다는 것을 나타냅니다.
- required: true는 이 매개변수가 필수라는 의미입니다.
responses:
- '404': 책을 찾지 못했을 때의 응답을 정의합니다.
[연습문제]

이제 여러분 차례입니다! 다음 요구사항을 만족하는 새로운 경로를 추가해보세요:

경로: /authors
GET 메서드: 모든 저자 목록을 반환
POST 메서드: 새로운 저자를 추가

힌트: '/books' 경로를 참고하세요. 구조는 비슷하지만 저자 정보에 맞게 속성을 변경하면 됩니다.

[정답]

여러분의 paths 섹션이 다음과 비슷하다면 정답입니다:

paths:
  # (이전 /books와 /books/{bookId} 경로는 그대로 둡니다)
  /authors:
    get:
      summary: List all authors
      description: Retrieves a list of all authors
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
    post:
      summary: Add a new author
      description: Adds a new author to the system
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
                - name
      responses:
        '201':
          description: Author created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string

축하합니다! 이번 파트에서 우리는 OpenAPI 스키마의 paths 섹션을 자세히 살펴보았습니다. API 경로를 정의하고, 다양한 HTTP 메서드를 사용하며, 경로 매개변수를 활용하는 방법을 배웠습니다.

이제 여러분은 기본적인 API 구조를 OpenAPI 스키마로 표현할 수 있게 되었습니다. 이는 API 설계의 중요한 첫 걸음입니다.

다음 파트에서는 components 섹션을 살펴보고, 재사용 가능한 스키마 요소를 정의하는 방법에 대해 배워보겠습니다. 궁금한 점이 있다면 언제든 물어보세요. 다음 파트에서 만나요!