TIL [HTTP - REST API 구현 및 문서 작성] #23.03.23

Swagger

Swagger는 RESTful API를 설계, 문서화 및 사용하는 데 도움을 주는 오픈 소스 소프트웨어 프레임워크입니다.

개발자는 OpenAPI 사양(이전에는 Swagger 사양이라 불렸음)을 사용하여 기계가 읽을 수 있는 형식으로 API를 설명할 수 있습니다. OpenAPI 사양은 RESTful API를 설명하는 표준으로서 다양한 도구와 플랫폼 간의 상호 운용성을 제공합니다.

Swagger를 사용하면 개발자는 API의 엔드포인트, 매개변수, 응답 및 기타 세부 정보를 설명하는 Swagger 파일을 작성할 수 있습니다. 이 파일은 자동으로 문서화를 생성하는 데 사용될 수 있으며, 이를 통해 개발자 및 사용자가 API를 사용하는 방법을 이해할 수 있습니다. 또한 Swagger를 사용하여 다양한 프로그래밍 언어에서 클라이언트 라이브러리를 생성할 수 있으며, 이를 통해 개발자가 API를 사용하기 쉬워집니다.

전반적으로 Swagger는 API 개발을 단순화하고 보다 넓은 대중에게 접근 가능하게 만들어, API를 설명하고 문서화하는 표준화된 방법을 제공합니다.

예시로, 다음은 Swagger로 작성된 간단한 API 설명서입니다.

openapi: 3.0.0
info:
  title: My API
  description: This is a simple API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: Get a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    age:
                      type: integer

위 예시는 "My API"라는 제목을 가진 버전 1.0.0의 간단한 API입니다. 이 API에서는 /users 경로에서 GET 요청을 수행하면 사용자 목록을 반환합니다. 반환되는 데이터는 JSON 배열로, 사용자의 이름과 나이 정보를 포함합니다. 이러한 정보를 기반으로 자동으로 문서화가 생성될 수 있습니다.

OpenAPI 명세서

어떤 완성된 웹사이트로 API를 제공하면 좋겠지만, API 문서를 가독성 있게 만드는 것 자체가 큰 일입니다. 따라서 API 문서에 필요한 각종 항목의 내용을 정해진 규칙에 맞게 JSON이나 YAML 문서로 작성해놓으면, 멋진 API 문서가 만들어지도록 만든 서비스가 존재합니다.

바로 Swagger라는 서비스입니다. 특히 그 중에서도 Swagger Editor를 사용하면 YAML을 API 문서로 변환해줍니다.
https://swagger.io/tools/swagger-editor/
YAML은 데이터 포맷이면서, 동시에 마크업 언어입니다. 해당 문법에 대해서는 별도로 다룹니다. 문법을 몰라도 작성할 수 있을 만큼 쉽습니다.

당연히 코드로 작성하는 YAML 파일에는 규칙이 존재합니다. 이 규칙을 OpenAPI 명세라고 부릅니다.
현재는 3.0.x 버전을 주로 사용하고 있습니다.

API 문서 살펴보기

왼쪽이 YAML 파일, 오른쪽이 결과물입니다.
결과물에는 엔드포인트와 메소드 및 Path, 그리고 Path를 누르면, 어떤 응답이 오는지까지 시각적으로 잘 표현되어 있습니다.

다음의 예제는 반려동물의 ID를 통해 반려동물의 정보를 조회하는 엔드포인트입니다.

---

과제

다음 기능에 대한 REST API 모범 사례를 연구해서 제출하세요.

• 조회
  - 특정 블로그 글에 달린 댓글 조회
• 기타 (어떤 메소드가 적합한지 고민해보세요!)
  - 블로그 글 좋아요
  - 블로그 글 좋아요 취소
  - 다른 글쓴이 팔로우

특정 블로그 글에 달린 댓글 조회

• HTTP GET 메서드를 사용하여 특정 블로그 게시물의 댓글을 가져옵니다.
• 올바른 URL 구조를 사용하여 게시물과 해당 댓글을 식별합니다. 예를 들어 "/posts/{post_id}/comments"와 같이 사용합니다.
• 클라이언트를 압도하지 않고 성능을 향상시키기 위해 요청 당 반환되는 댓글 수를 제한하는 페이지네이션을 사용합니다.
• 응답 시간을 향상시키고 서버 부하를 줄이기 위해 ETag 또는 Last-Modified와 같은 캐싱 메커니즘을 사용합니다.
• 검색 과정에서 문제가 발생한 경우 의미 있는 오류 메시지와 상태 코드를 제공하기 위해 오류 처리를 사용합니다.
• 특정 블로그 게시물의 댓글에만 인증된 사용자만 접근할 수 있도록 인증 및 권한 부여 메커니즘을 추가하는 것이 좋습니다.

블로그 글 좋아요 / 블로그 글 좋아요 취소

HTTP POST 메서드를 사용하여 블로그 게시물을 좋아합니다.
HTTP DELETE 메서드를 사용하여 좋아요를 취소합니다.
적절한 URL 구조를 사용하여 게시물을 식별합니다. 예를 들어 "/posts/{post_id}/like"와 같이 사용합니다.
좋아요 또는 좋아요 취소를 한 사용자는 인증 및 권한 부여 메커니즘을 통해 인가되어야 합니다.
작업의 성공 또는 실패를 나타내기 위해 적절한 상태 코드를 사용합니다.
남용을 방지하고 성능을 향상시키기 위해 요청 비율 제한을 추가하는 것이 좋습니다.
좋아요 또는 좋아요 취소 과정에서 문제가 발생한 경우 의미 있는 오류 메시지와 상태 코드를 제공하기 위해 오류 처리를 사용합니다.

다른 글쓴이 팔로우

HTTP POST 메서드를 사용하여 다른 글쓴이를 팔로우합니다.
HTTP DELETE 메서드를 사용하여 팔로우를 취소합니다.
적절한 URL 구조를 사용하여 글쓴이를 식별합니다. 예를 들어 "/authors/{author_id}/follow"와 같이 사용합니다.
팔로우 또는 팔로우 취소를 한 사용자는 인증 및 권한 부여 메커니즘을 통해 인가되어야 합니다.
작업의 성공 또는 실패를 나타내기 위해 메시지와 상태 코드를 제공하여야 합니다.