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

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

API 문서화의 중요성

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

API 사용 방법을 쉽게 이해할 수 있습니다.
개발 시간을 단축시킵니다.
API 사용 시 발생할 수 있는 오류를 줄입니다.
API 변경 사항을 쉽게 추적할 수 있습니다.

Swagger UI 사용하기

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

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

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

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

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

API 엔드포인트 탐색

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

요청 파라미터
요청 본문 스키마
가능한 응답 및 응답 스키마
인증 요구사항

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

설명: "List all books"
응답: 200 OK와 함께 Book 객체의 배열
필요한 인증: API Key 또는 OAuth2의 read:books 스코프

API 테스트하기

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

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

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

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

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

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

문서 개선하기

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
      # ... (나머지 부분은 그대로 둡니다)

버전 관리

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'
# ... (나머지 부분은 그대로 둡니다)

연습문제

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

'/books/{bookId}/reviews' GET 엔드포인트 추가: 특정 책의 리뷰 목록을 반환
이 엔드포인트에 대한 상세한 설명과 예제 응답 추가
API 버전을 1.2.0으로 업데이트하고, 변경 사항 설명 추가

정답

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

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

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

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

마무리

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

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

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

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