01. 간단한 기획 후, API 명세를 작성해 보자

일단 만들고, 필요에 의해 개선하자. 무턱대고 정답에 가까운 방법을 엿들어 개발하는 일은 없도록 하자. 이번엔 간단한 웹 사이트를 하나 개발할 생각이다. 내가 작성한 게시물이 하나 있고, 그 게시물에는 여러 사람이 댓글을 남길 수 있도록 만들 것이다. 고려해야 할 사항은 다음과 같다.

 

1. 게시물은 나(어드민)만 작성하고 수정할 수 있어야 한다.
2. 게시물에는 여러 사람이 작성한 댓글들을 순차적으로 보여준다.

 

논리구조상 게시물이 먼저 구현되어야 할 것 같은데, 게시물 작성 및 수정에는 특수한 조건이 필요하므로 댓글 기능 먼저 구현하기로 하였다. 댓글 기능에도 사실 추가하고 싶은 게 몇 가지 있지만 일단은 익명으로 누구나 작성할 수 있도록 개발해야겠다.

---

 

API 명세부터 작성해 보았다. 혼자 진행하는 프로젝트라 꼭 선행되어야 하는 부분은 아니지만, 협업이라 생각하고 간단히 준비했다. 아래는 명세 작성 시 유의사항을 정리한 것이다. (명세 형식은 표준으로 취급되는 Swagger를 참고했다.)

 

• RESTful 원칙 (필수):
  각 엔드포인트가 명확한 리소스(comments)와 동작(GET, POST)을 나타내도록 한다.
• HTTP 상태 코드 (필수):
  적절한 HTTP 상태 코드를 사용한다. (201 Created, 200 OK, 400 Bad Request 등)
• 데이터 형식 (필수):
  application/json을 표준으로 사용한다.
• 응답 스키마 (필수):
  반환되는 데이터의 구조와 각 필드의 타입을 명확히 정의한다.
• 예시 (선택):
  실제 통신에서 오고 갈 데이터를 예시로 들어 이해를 돕는다.
• 오류 처리 (선택):
  발생 가능한 오류 상황(예: 유효성 검사 실패)에 대한 응답도 정의한다.

---

 

1. POST /api/comments (댓글 생성)

• 설명: 새로운 댓글을 생성한다.
• HTTP 메서드: POST
• 엔드포인트: /api/comments
• 요청 바디 (Request Body):
  • Content-Type: application/json
  • 스키마:

      {
          "content": "String" // (필수 데이터)
      }

  • 예시:

      {
          "content": "댓글 내용"
      }

• 응답 (Responses):
  • 201 Created (성공적으로 댓글이 생성됨)
    • Content-Type: application/json
    • 스키마 (예시):

        {
            "id": long,                            // 생성된 댓글 고유 ID
            "content": "댓글 내용",                 // 댓글 내용
            "createdAt": "2025-07-22T10:30:00Z"    // (ISO 8601 형식)
        }

  • 400 Bad Request (요청 데이터가 유효하지 않음)
    • 설명: content가 누락되거나 유효하지 않은 경우
    • Content-Type: application/json
    • 스키마 (예시):

        {
            "timestamp": "2025-07-22T10:30:00.000+00:00",
            "status": 400,
            "error": "Bad Request",
            "message": "content cannot be empty",
            "path": "/api/comments"
        }

 

2. GET /api/comments (모든 댓글 조회)

• 설명: 현재까지 작성된 모든 댓글 목록을 최신순으로 조회한다.
• HTTP 메서드: GET
• 엔드포인트: /api/comments
• 요청 파라미터 (Request Parameters): 없음
• 응답 (Responses):
  • 200 OK (성공적으로 댓글 목록을 조회함)
    • Content-Type: application/json
    • 스키마 (예시):

        [
            {
                "id": 1,
                "content": "첫 번째 댓글",
                "createdAt": "2025-07-22T10:30:00Z"
            },
            {
                "id": 2,
                "content": "두 번째 댓글",
                "createdAt": "2025-07-22T10:40:00Z"
            }
        ]

---

 

데이터베이스는 MySQL로 결정했다. 아무래도 도커를 사용할 예정인데, 도커에 관해 이야기할 것들이 많아, 이와 관련하여 다음 포스트에서 이어가도록 하겠다.