Day 074 - 과제 제출, ERD와 API 명세서가 담긴 리드미(README)는 어떻게 작성하면 좋을까?

1️⃣ [링크] 일정 관리 앱 Develop 리드미(README) 1단계
2️⃣ [링크] 일정 관리 앱 Develop 리드미(README) 2단계
3️⃣ [링크] 일정 관리 앱 Develop 리드미(README) 3단계, 4단계
4️⃣ [링크] 일정 관리 앱 Develop 리드미(README) 5단계, 6단계
5️⃣ [링크] 일정 관리 앱 Develop 리드미(README) 7단계, 8단계

 

리드미(README)를 다섯 편이나 작성했으니 원 없이 썼다고 말해도 과장이 아닐 터다. 각 과제의 데이터베이스(database) 구조에 맞춰 내용을 고치는 내내 미리 틀을 잡아두길 정말 잘했다는 안도감이 맴돌았다. 프로젝트를 하다 보면 문서 작성할 일이 정말 많은데, 이번에 실컷 연습했다. 리드미를 작성하면서 팀원들이 고생하는 모습을 종종 마주했고, 마크다운(Markdown) 문법에 서투른 사람이라면 누구나 어려울 수밖에 없는지라, 조금이나마 도움이 되길 바라는 마음으로 리드미에 들어간 각 내용을 정리했다. 특히나 코드를 복사해서 바로 사용할 수 있도록 작성했다.

 

1. 리드미(README) 전체 틀 

# 🗓️ 제목 

## 💻 프로젝트 소개 
- 프로젝트 목적
- 개인 프로젝트인지 아니면 팀 프로젝트인지 
- 해당 프로젝트가 어떤 인터페이스(interface)를 기반으로 설계되었는지

## 📆 개발 기간
- **학습 기간**: 08/12/2024 – 13/12/2024
- **개발 기간**: 13/12/2024 – 19/12/2024

## 🛠️ 기술 구성 
- Java 17
- Spring Boot 3.4.0
- Spring Data JPA
- 기타 등등

## 🔗 ERD (Entity Relationship Diagram)

## 📜 API 명세서

## 📊 데이터베이스 스키마(Database Schema)

## 🚀 주요 기능
- 특정 항목을 강조하고 싶을 때는 백틱(``) 사용하기 
- `예시1`, `예시2`, `예시3`

## 🔍 특징 

## 📜 추가 정보

2. API 명세서

### 기본 정보
- 기본 URL :
- 응답 형식: JSON
- 문자 인코딩: UTF-8

### API 목록
#### API 엔드포인트(endpoint) - fieldName

| Method | URI | Req Body | Req Params | Path Vars | Resp Code |
|--------|-----|----------|------------|-----------|-----------|
| POST   |     |          |            |           |           | 
| GET    |     |          |            |           |           |
| GET    |     |          |            |           |           |
| PUT    |     |          |            |           |           |
| DELETE |     |          |            |           |           |

- URI: /plans/{id}, /members/signup 등등 
- Req Body: Request Body (e.g. username, password)
- Req Params: Request Parameters (e.g. page, size)
- Path Vars: Path Variables (e.g. id)
- Response Code: 200, 201 등등

### API 세부 정보
#### 요청 본문 세부 정보 - fieldName
1. **`POST` 제목**
    ```json
    {
        "Req Body1" : "설명1",
        "Req Body2" : "설명2"
    }
    ```

2. **`PUT` 제목**
    ```json
    {
        "Req Body1" : "설명1",
        "Req Body2" : "설명2"
    }
    ```

#### 응답 본문 세부 정보 - fieldName
1. **`GET` 제목**
    ```json
    [
        {
            "Resp Body1" : "설명1",
            "Resp Body2" : "설명2",
            "Resp Body3" : "yyyy-MM-dd HH:mm:ss"
        },
        {
            "Resp Body1" : "설명1",
            "Resp Body2" : "설명2",
            "Resp Body3" : "yyyy-MM-dd HH:mm:ss"
        }  
    ]
    ```

2. **`GET` 제목**
    ```json
    {
        "id" : 1,
        "Resp Body1" : "설명1",
        "Resp Body2" : "설명2",
        "Resp Body3": {
            "id": 1,
            "Resp Body3-1": "설명3-1"
            "Resp Body3-2": "설명3-2"
        }
    }
    ```

 

3. ERD

```mermaid
erDiagram
    ENTITY {
        id bigint PK
        column1 varchar(16)
        column2 datetime
    }
```

```mermaid
erDiagram
    ENTITY1 ||--o{ ENTITY2 : creates
    ENTITY1 {
        id bigint PK
        column1 varchar(32)
        column2 varchar(255)
        column3 timestamp
        column4 tinyint
    }
    ENTITY2 {
        id bigint PK
        column1 varchar(16)
        column2 tinyint
        entity1_id bigint FK
    }
```

```mermaid
erDiagram
    ENTITY1 ||--o{ ENTITY2 : creates
    ENTITY2 ||--o{ ENTITY3 : receives
    ENTITY1 ||--o{ ENTITY3 : writes
    ENTITY1 {
        id bigint PK
        column1 varchar(32)
        column2 varchar(128)
    }
    ENTITY2 {
        id bigint PK
        column1 varchar(16)
        column2 timestamp
        entity1_id bigint FK
    }
    COMMENTS {
        id bigint PK
        column1 varchar(255)
        entity1_id bigint FK
        entity2_id bigint FK
    }
```

4. 데이터베이스 스키마

```sql
CREATE TABLE entity2
(
    id         BIGINT AUTO_INCREMENT COMMENT '코멘트'
        PRIMARY KEY,
    column1    VARCHAR(255) NULL COMMENT '코멘트',
    column2    TINYINT NULL COMMENT '코멘트',
    column3    TIMESTAMP NULL COMMENT '코멘트',
    entity1_id  BIGINT NOT NULL COMMENT '코멘트',
    CONSTRAINT FK_ENTITY1_ID
        FOREIGN KEY (entity1_id) REFERENCES entity1 (id)
);
```