DevOps13일차 - swagger, 발표과제

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 파일에는 규칙이 존재합니다. 규칙대로 써야만 API 문서가 만들어지니까요. 이 규칙을 OpenAPI 명세라고 부릅니다. 현재는 3.0.x 버전을 주로 사용하고 있습니다.

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

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

두 번째 발표

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

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

특정 블로그 글에 달린 댓글 조회 REST API 모범 사례

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

블로그 글 좋아요 블로그 글 좋아요 취소의 REST API 모범 사례

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

다른 글쓴이 팔로우 REST API 모법 사례

• HTTP POST 메서드를 사용하여 다른 작가를 팔로우합니다. HTTP DELETE 메서드를 사용하여 팔로우를 취소합니다.
• 적절한 URL 구조를 사용하여 작가를 식별합니다. 예를 들어 "/authors/{author_id}/follow"와 같이 사용합니다.
• 팔로우 또는 팔로우 취소를 한 사용자는 인증 및 권한 부여 메커니즘을 통해 인가되어야 합니다.