[GPT Actions] 5. OpenAPI 스키마 문서화 및 테스트

안녕하세요! 이번 파트에서는 지금까지 작성한 OpenAPI 스키마를 활용하여 API 문서를 생성하고, 이를 통해 API를 테스트하는 방법에 대해 알아보겠습니다. 문서화는 API를 이해하고 사용하는 데 매우 중요한 과정입니다.

1. API 문서화의 중요성

API 문서는 개발자들이 API를 이해하고 사용하는 데 필수적입니다. 잘 작성된 문서는 다음과 같은 이점이 있습니다:

• API 사용 방법을 쉽게 이해할 수 있습니다.

• 개발 시간을 단축시킵니다.

• API 사용 시 발생할 수 있는 오류를 줄입니다.

• API 변경 사항을 쉽게 추적할 수 있습니다.

2. Swagger UI 사용하기

Swagger UI는 OpenAPI 스키마를 기반으로 대화형 API 문서를 생성해주는 도구입니다. 온라인에서 사용할 수 있는 Swagger Editor를 통해 우리의 스키마를 시각화해 봅시다.

a) https://editor.swagger.io/ 에 접속합니다.

b) 왼쪽 패널에 지금까지 작성한 OpenAPI 스키마를 붙여넣습니다.

c) 오른쪽 패널에서 생성된 문서를 확인합니다.

3. API 엔드포인트 탐색

Swagger UI에서 각 엔드포인트를 클릭하면 상세 정보를 볼 수 있습니다:

• 요청 파라미터

• 요청 본문 스키마

• 가능한 응답 및 응답 스키마

• 인증 요구사항

예를 들어, '/books' GET 엔드포인트를 클릭하면 다음과 같은 정보를 볼 수 있습니다:

• 설명: "List all books"

• 응답: 200 OK와 함께 Book 객체의 배열

• 필요한 인증: API Key 또는 OAuth2의 read:books 스코프

4. API 테스트하기

Swagger UI를 사용하면 API를 직접 테스트해볼 수 있습니다. 실제 서버가 구현되어 있다면 다음과 같이 테스트할 수 있습니다:

a) 'Try it out' 버튼을 클릭합니다.

b) 필요한 파라미터를 입력합니다.

c) 인증 정보를 제공합니다 (필요한 경우).

d) 'Execute' 버튼을 클릭합니다.

응답을 확인하고 API가 예상대로 작동하는지 확인할 수 있습니다.

5. 문서 개선하기

API 문서를 더욱 유용하게 만들기 위해 몇 가지 추가 정보를 스키마에 포함시킬 수 있습니다:

a) 예제 추가:

paths:
  /books:
    get:
      summary: List all books
      responses:
        '200':
          description: Successful response
          content:
            application/json:    
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
              example:
                - id: 1
                  title: "To Kill a Mockingbird"
                  author:
                    id: 1
                    name: "Harper Lee"
                  publicationYear: 1960
                - id: 2
                  title: "1984"
                  author:
                    id: 2
                    name: "George Orwell"
                  publicationYear: 1949

b) 상세한 설명 추가:

paths:
  /books/{bookId}:
    get:
      summary: Get a book by ID
      description: |
        This endpoint retrieves a specific book by its ID.
        The response includes detailed information about the book,
        including its title, author, and publication year.
      parameters:
        - name: bookId
          in: path
          required: true
          schema:
            type: integer
          description: The unique identifier of the book
      # ... (나머지 부분은 그대로 둡니다)

6. 버전 관리

API가 발전함에 따라 버전 관리가 중요해집니다. OpenAPI 스키마에서 버전 정보를 명시적으로 포함시킬 수 있습니다:

openapi: 3.1.0
info:
  title: My Awesome Bookstore API
  version: 1.1.0
  description: |
    Version 1.1.0 includes the following changes:
    - Added new endpoint: GET /books/{bookId}/reviews
    - Updated POST /books to require 'publicationYear'
# ... (나머지 부분은 그대로 둡니다)

7. 연습문제

이제 여러분 차례입니다! 다음 요구사항을 만족하도록 스키마를 수정해보세요:

• '/books/{bookId}/reviews' GET 엔드포인트 추가: 특정 책의 리뷰 목록을 반환

• 이 엔드포인트에 대한 상세한 설명과 예제 응답 추가

• API 버전을 1.2.0으로 업데이트하고, 변경 사항 설명 추가

8. 정답

여러분의 수정된 스키마가 다음과 비슷하다면 정답입니다:

openapi: 3.1.0
info:
  title: My Awesome Bookstore API
  version: 1.2.0
  description: |
    Version 1.2.0 includes the following changes:
    - Added new endpoint: GET /books/{bookId}/reviews
    - Updated API documentation with more examples and descriptions

paths:
  # ... (기존 엔드포인트들은 그대로 둡니다)
  /books/{bookId}/reviews:
    get:
      summary: Get reviews for a specific book
      description: |
        This endpoint retrieves all reviews for a specific book identified by its ID.
        The response includes a list of reviews, each containing the reviewer's name,
        rating, and comment.
      parameters:
        - name: bookId
          in: path
          required: true
          schema:
            type: integer
          description: The unique identifier of the book
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Review'
              example:
                - id: 1
                  bookId: 1
                  rating: 5
                  comment: "A classic that everyone should read!"
                - id: 2
                  bookId: 1
                  rating: 4
                  comment: "Powerful story, but a bit slow at times."
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    Review:
      type: object
      properties:
        id:
          type: integer
        bookId:
          type: integer
        rating:
          type: integer
          minimum: 1
          maximum: 5
        comment:
          type: string
      required:
        - bookId
        - rating

  # ... (다른 컴포넌트들은 그대로 둡니다)

9. 마무리

축하합니다! 이번 파트에서는 OpenAPI 스키마를 활용하여 API 문서를 생성하고 테스트하는 방법을 배웠습니다. Swagger UI를 사용하여 대화형 문서를 만들고, 예제와 상세한 설명을 추가하여 문서의 품질을 높이는 방법도 알아보았습니다.

잘 작성된 API 문서는 개발자들이 API를 쉽게 이해하고 사용할 수 있게 해줍니다. 또한 버전 관리를 통해 API의 변경 사항을 명확히 전달할 수 있습니다.

이것으로 OpenAPI 스키마 작성에 대한 기본적인 내용을 모두 다루었습니다. 실제 프로젝트에서는 이러한 지식을 바탕으로 더 복잡하고 다양한 API를 설계하고 문서화할 수 있을 것입니다.

API 설계와 문서화 과정에서 궁금한 점이 있다면 언제든 물어보세요. 여러분의 API 개발 여정을 응원합니다!