Skip to content

Release v1.1.2

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 12 Jul 12:27
v1.1.2
ab74c34
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

릴리스 v1.1.2

FastAPI 명세서

📌 ChatBot FastAPI 명세서

📢 개요

  • API 이름: ChatBot FastAPI
  • 설명: 쳇봇 데이터 관리 및 이메일 인증 API
  • 버전: 1.1.2
  • 로고:
    ChatBot 로고

이 API는 MongoDB 데이터 관리와 이메일 인증을 위한 기능을 제공합니다.

📍 엔드포인트 목록

🔹 MongoDB 라우터

📌 데이터베이스 관리

  • GET /mongo/db

    • 설명: 데이터베이스 서버에 있는 모든 데이터베이스의 목록을 반환합니다.
    • 응답: 데이터베이스 목록 및 관련 링크를 포함한 JSON 객체

  • GET /mongo/collections

    • 설명: 현재 선택된 데이터베이스 내의 모든 컬렉션 이름을 반환합니다.
    • 쿼리 파라미터:
      파라미터명 필수 여부 설명
      db_name 필수 데이터베이스 이름
    • 응답: 컬렉션 목록 및 관련 링크를 포함한 JSON 객체

🔹 MongoDB / Offices

📌 오피스 채팅방 관리

  • POST /mongo/offices/users/{user_id}

    • 설명: 새로운 유저 채팅 문서(채팅 로그)를 MongoDB에 생성합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
    • 응답: 생성된 채팅방 ID 및 관련 API 링크 정보

  • GET /mongo/offices/users/{user_id}/documents/{document_id}

    • 설명: 생성된 채팅 문서의 채팅 로그를 MongoDB에서 불러옵니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
    • 응답: 채팅 로그 내용 및 관련 API 링크 정보

  • PUT /mongo/offices/users/{user_id}/documents/{document_id}

    • 설명: 생성된 채팅 문서에 유저의 채팅 데이터를 저장합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
    • 요청 본문: 
      {
  "input_data": "안녕하세요, 챗봇!",
  "output_data": "안녕하세요! 무엇을 도와드릴까요?"
}
      필드명 타입 제약조건 설명 예시
      input_data string minLength=1, maxLength=500 사용자 입력 문장 "안녕하세요, 챗봇!"
      output_data string minLength=1, maxLength=8191 챗봇 출력 문장 "안녕하세요! 무엇을 도와드릴까요?"
    • 응답: 저장 결과 메시지 및 관련 API 링크 정보

  • PATCH /mongo/offices/users/{user_id}/documents/{document_id}

    • 설명: 기존 채팅 문서에 유저의 채팅 데이터를 수정합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
    • 요청 본문: PUT 요청과 동일한 형식
    • 응답: 수정 결과 메시지 및 관련 API 링크 정보

  • DELETE /mongo/offices/users/{user_id}/documents/{document_id}

    • 설명: 유저의 채팅방을 삭제합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
    • 응답: 삭제 결과 메시지 및 관련 API 링크 정보

  • DELETE /mongo/offices/users/{user_id}/documents/{document_id}/idx/{index}

    • 설명: 최신 대화 ~ 선택된 채팅을 로그에서 삭제합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
      index integer 삭제를 시작할 채팅 로그의 인덱스
    • 응답: 삭제 결과 메시지 및 관련 API 링크 정보

🔹 MongoDB / Characters

📌 캐릭터 채팅방 관리

  • POST /mongo/characters/users/{user_id}

    • 설명: 새로운 유저 채팅 문서(채팅 로그)를 MongoDB에 생성합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
    • 요청 본문: 
      {
  "character_idx": 1
}
      필드명 타입 설명 예시
      character_idx integer 캐릭터 id 1
    • 응답: 생성된 채팅방 ID 및 관련 API 링크 정보

  • GET /mongo/characters/users/{user_id}/documents/{document_id}

    • 설명: 생성된 채팅 문서의 채팅 로그를 MongoDB에서 불러옵니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
    • 응답: 채팅 로그 내용, 캐릭터 인덱스 및 관련 API 링크 정보

  • PUT /mongo/characters/users/{user_id}/documents/{document_id}

    • 설명: 생성된 채팅 문서에 유저의 채팅 데이터를 저장합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
    • 요청 본문: 
      {
  "img_url": "https://drive.google.com/thumbnail?id=12PqUS6bj4eAO_fLDaWQmoq94-771xfim",
  "input_data": "안녕하세요, 챗봇!",
  "output_data": "안녕하세요! 무엇을 도와드릴까요?"
}
      필드명 타입 제약조건 설명 예시
      img_url string minLength=1, maxLength=2048 이미지 URL "https://drive.google.com/thumbnail?id=12PqUS6bj4eAO_fLDaWQmoq94-771xfim"
      input_data string minLength=1, maxLength=500 사용자 입력 문장 "안녕하세요, 챗봇!"
      output_data string minLength=1, maxLength=8191 챗봇 출력 문장 "안녕하세요! 무엇을 도와드릴까요?"
    • 응답: 저장 결과 메시지 및 관련 API 링크 정보

  • PATCH /mongo/characters/users/{user_id}/documents/{document_id}

    • 설명: 기존 채팅 문서에 유저의 채팅 데이터를 수정합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
    • 요청 본문: PUT 요청과 동일한 형식
    • 응답: 수정 결과 메시지 및 관련 API 링크 정보

  • DELETE /mongo/characters/users/{user_id}/documents/{document_id}

    • 설명: 유저의 채팅방을 삭제합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
    • 응답: 삭제 결과 메시지 및 관련 API 링크 정보

  • DELETE /mongo/characters/users/{user_id}/documents/{document_id}/idx/{index}

    • 설명: 최신 대화 ~ 선택된 채팅을 로그에서 삭제합니다.
    • 경로 파라미터:
      파라미터명 타입 설명
      user_id string 유저 ID
      document_id string 채팅방 ID
      index integer 삭제를 시작할 채팅 로그의 인덱스
    • 응답: 삭제 결과 메시지 및 관련 API 링크 정보

🔹 인증

📌 이메일 인증

  • POST /auth/verification/send

    • 설명: 사용자 이메일로 인증 코드를 전송합니다.
    • 요청 본문: 
      {
  "user_id": "shaa97102",
  "email": "user@example.com"
}
      필드명 타입 제약조건 설명 예시
      user_id string minLength=1, maxLength=50 유저 ID "shaa97102"
      email string 유효한 이메일 형식 인증 코드를 전송할 이메일 주소 "user@example.com"
    • 응답: 인증 코드 전송 결과 메시지

  • POST /auth/verification/verify

    • 설명: 사용자로부터 받은 인증 코드를 검증합니다.
    • 요청 본문: 
      {
  "user_id": "shaa97102",
  "email": "user@example.com",
  "code": "A12B34"
}
      필드명 타입 제약조건 설명 예시
      user_id string minLength=1, maxLength=50 유저 ID "shaa97102"
      email string 유효한 이메일 형식 인증 코드를 전송한 이메일 주소 "user@example.com"
      code string minLength=6, maxLength=6 6자리 인증 코드 "A12B34"
    • 응답: 인증 코드 검증 결과 메시지

🛠 응답 구조

일반 응답

  • 정상 응답 예시: 
    {
  "status": "success",
  "message": "인증 코드가 전송되었습니다. 이메일을 확인해주세요."
}

HATEOAS 링크

  • 링크 포함 응답 예시: 
    {
  "Document ID": "614a123456789b0d323e456f",
  "_links": [
    {
      "href": "/mongo/offices/users/shaa97102",
      "rel": "self",
      "type": "GET",
      "title": "유저 채팅방 ID 생성"
    },
    {
      "href": "/mongo/offices/users/shaa97102/documents/614a123456789b0d323e456f",
      "rel": "/users/shaa97102/documents/614a123456789b0d323e456f",
      "type": "GET",
      "title": "유저 채팅 불러오기"
    }
  ]
}

오류 응답

  • 오류 응답 예시: 
    {
  "status": "error",
  "detail": "인증 코드가 일치하지 않습니다.",
  "code": "invalid_verification_code"
}

SpringBoot RoomController 명세서

📢 개요

  • API 이름: RoomController
  • 설명: 채팅방 및 대화 관리 API

이 API는 Office 모드와 Character 모드의 채팅방을 생성, 관리하고 대화 기록을 저장, 조회, 수정, 삭제하는 기능을 제공합니다.

📍 엔드포인트 목록

🔹 Office 채팅방 (정보 제공 모드)

📌 Office 채팅방 생성

  • POST /server/rooms/office
    • 설명: 새로운 Office 채팅방을 생성합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 응답 예시 
      {
  "status": 200,
  "message": "채팅방이 성공적으로 생성되었습니다.",
  "mysql_officeroom": {
    "idx": 3,
    "userid": "test_VIP",
    "mongo_chatroomid": "8430b4dc-45a0-47ba-a3e4-a7d01edbfcf3",
    "createdAt": "2025-03-24T17:54:32.230555456",
    "updatedAt": "2025-03-24T17:54:32.230581553"
  }
}

📌 Office 채팅방 목록 조회

  • GET /server/rooms/office
    • 설명: 사용자의 Office 채팅방 목록을 조회합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 응답 예시 
      {
  "status": 200,
  "rooms": [
    {
      "roomid": "5df8cf5a-baae-4a53-be70-5eb2215fc237",
      "Title": "파이썬에 대해서 자..."
    }
  ]
}

📌 Office 채팅방 삭제

  • DELETE /server/rooms/office/{roomId}
    • 설명: 특정 Office 채팅방을 삭제합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
    • 응답 예시 
      {
  "status": 200,
  "message": "채팅방이 성공적으로 삭제되었습니다.",
  "response": {
    "Result": "Successfully deleted document with ID: 8430b4dc-45a0-47ba-a3e4-a7d01edbfcf3"
  }
}

📌 Office AI 응답 받기

  • POST /server/rooms/office/{roomId}/log
    • 설명: Office 채팅방에서 AI 응답을 받습니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
    • 요청 본문 
      {
  "input_data_set": "인공지능의 미래 전망에 대해 알려주세요.",
  "route_set": "Llama",
  "google_access_set": "true"
}
      필드명 타입 제약조건 설명 예시
      input_data_set string 필수 사용자 입력 문장 "인공지능의 미래 전망에 대해 알려주세요."
      route_set string 필수 사용할 AI 모델 종류 "Llama" 또는 "gpt4o_mini"
      google_access_set string 선택 검색 기능 활성화 여부 "true" 또는 "false"
    • 응답 예시 
      {
  "status": 200,
  "message": "물론입니다! 아래는 파이썬에 대한 자세한 정보입니다.\\n\\n```markdown\\n# 파이썬(Python)\\n\\n## 개요\\n파이썬은 1991년 귀도 반 로썸(Guido van Rossum)에 의해 처음 출시된 고급 프로그래밍 언어입니다. 파이썬은 읽기 쉽고, 코드가 간결하며, 다양한 프로그래밍 패러다임을 지원하는 것이 특징입니다. \\n\\n## 주요 특징\\n- **간결한 문법**: 파이썬은 코드가 명확하고 읽기 쉽도록 설계되었습니다.\\n- **인터프리터 언어**: 코드를 한 줄씩 실행할 수 있어 개발과 디버깅이 용이합니다.\\n- **다양한 라이브러리**: 데이터 과학, 웹 개발, 인공지능 등 다양한 분야에서 사용되는 방대한 라이브러리와 프레임워크를 제공합니다.\\n- **객체 지향**: 파이썬은 객체 지향 프로그래밍을 지원하여 코드 재사용과 구조적인 설계를 가능하게 합니다.\\n- **크로스 플랫폼**: Windows, macOS, Linux 등 다양한 운영 체제에서 실행 가능합니다.\\n\\n## 설치\\n파이썬을 설치하기 위해서는 [Python 공식 웹사이트](https://www.python.org/downloads/)에서 최신 버전을 다운로드할 수 있습니다.\\n\\n### 설치 방법 (Windows)\\n1"
}

📌 Office 채팅 로그 불러오기

  • GET /server/rooms/office/{roomId}/logs
    • 설명: 특정 Office 채팅방의 대화 로그를 불러옵니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
    • 응답 예시 
      {
  "status": 200,
  "logs": {
    "id": "5df8cf5a-baae-4a53-be70-5eb2215fc237",
    "value": [
      {
        "index": 1,
        "input_data": "파이썬에 대해서 자세하게 정보를 정리해서 마크다운으로 답변을 줄래?",
        "output_data": "물론입니다! 아래는 파이썬에 대한 자세한 정보입니다.\\n\\n```markdown\\n# 파이썬(Python)\\n\\n## 개요\\n파이썬은 1991년 귀도 반 로썸(Guido van Rossum)에 의해 처음 출시된 고급 프로그래밍 언어입니다. 파이썬은 읽기 쉽고, 코드가 간결하며, 다양한 프로그래밍 패러다임을 지원하는 것이 특징입니다. \\n\\n## 주요 특징\\n- **간결한 문법**: 파이썬은 코드가 명확하고 읽기 쉽도록 설계되었습니다.\\n- **인터프리터 언어**: 코드를 한 줄씩 실행할 수 있어 개발과 디버깅이 용이합니다.\\n- **다양한 라이브러리**: 데이터 과학, 웹 개발, 인공지능 등 다양한 분야에서 사용되는 방대한 라이브러리와 프레임워크를 제공합니다.\\n- **객체 지향**: 파이썬은 객체 지향 프로그래밍을 지원하여 코드 재사용과 구조적인 설계를 가능하게 합니다.\\n- **크로스 플랫폼**: Windows, macOS, Linux 등 다양한 운영 체제에서 실행 가능합니다.\\n\\n## 설치\\n파이썬을 설치하기 위해서는 [Python 공식 웹사이트](https://www.python.org/downloads/)에서 최신 버전을 다운로드할 수 있습니다.\\n\\n### 설치 방법 (Windows)\\n1",
        "timestamp": "2025-03-24 18:26:45"
      }
    ]
  }
}

📌 Office 채팅 로그 수정

  • PUT /server/rooms/office/{roomId}/logs
    • 설명: 기존 Office 채팅 로그의 최신 부분을 수정합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
    • 요청 본문 
      {
  "index":1,
  "input_data_set":"우리 대화를 몇번했지?",
  "route_set" : "gpt4o_mini",
  "google_access_set": "true"
}
      필드명 타입 제약조건 설명 예시
      index integer 필수 수정할 로그의 인덱스 1
      input_data_set string 필수 수정할 사용자 입력 문장 "머신러닝과 딥러닝의 차이점에 대해 자세히 설명해주세요."
      route_set string 필수 사용할 AI 모델 종류 "Llama" 또는 "gpt4o_mini"
      google_access_set string 선택 검색 기능 활성화 여부 "true" 또는 "false"
    • 응답 예시 
      {
  "status": 200,
  "message": "채팅 로그가 성공적으로 수정되었습니다.",
  "response": {
    "Result": "Successfully added data to document with ID: fb943add-a683-431e-a672-1174a25327ad, Values:1"
  }
}

📌 Office 채팅 로그 삭제

  • DELETE /server/rooms/{roomId}/logs/{logIndex}
    • 설명: 특정 Office 채팅 로그를 삭제합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
      index 마지막 인덱스 로그부터 입력한 인덱스 로그까지 삭제(10까지의 index라면 5 선택 시 10~5까지 삭제)
    • 응답 예시 
      {
  "status": 200,
  "message": "해당 로그가 성공적으로 삭제되었습니다.",
  "response": {
    "Result": "Successfully removed data from index: 1 to the end in document with ID: 5df8cf5a-baae-4a53-be70-5eb2215fc237"
  }
}

🔹 Character 채팅방 (캐릭터 기반 대화 모드)

📌 Character 채팅방 생성

  • POST /server/rooms/character
    • 설명: 새로운 Character 채팅방을 생성합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 요청 본문 
      {
  "character_idx": 1
}
      필드명 타입 필수 설명
      character_idx integer 필수 생성할 캐릭터의 인덱스
    • 응답 예시 
      {
  "status": 200,
  "message": "채팅방이 성공적으로 생성되었습니다.",
  "mysql_characterroom": {
    "idx": 4,
    "userid": "test_VIP",
    "charactersIdx": 1,
    "mongo_chatroomid": "e44e4840-d779-49f4-92a6-a289e89d25fc",
    "createdAt": "2025-03-24T17:59:13.167108508",
    "updatedAt": "2025-03-24T17:59:13.167150975"
  }
}

📌 Character 채팅방 목록 조회

  • GET /server/rooms/character
    • 설명: 사용자의 Character 채팅방 목록을 조회합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 응답 예시 
      {
  "status": 200,
  "rooms": [
    {
      "roomid": "e44e4840-d779-49f4-92a6-a289e89d25fc",
      "Title": "hi, what's..."
    }
  ]
}

📌 Character 채팅방 삭제

  • DELETE /server/rooms/character/{roomId}
    • 설명: 특정 Character 채팅방을 삭제합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
    • 응답 예시 
      {
  "status": 200,
  "message": "채팅방이 성공적으로 삭제되었습니다.",
  "response": {
    "Result": "Successfully deleted document with ID: a9022281-418a-4f75-bcc8-6cafc31633eb"
  }
}

📌 Character AI 응답 받기

  • POST /server/rooms/character/{roomId}/logs
    • 설명: Character 채팅방에서 AI 응답을 받습니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
    • 요청 본문 
      {
  "input_data_set": "hi, what's your name?",
  "route_set": "gpt4o_mini"
}
      필드명 타입 필수 설명
      input_data_set string 필수 사용자 입력 문장
      route_set string 필수 사용할 AI 모델 종류
    • 응답 예시 
      {
  "status": 200,
  "message": "G-g-good…b-blessings! I-I’m Rachel. It’s n-nice to m-meet you! How can I h-help you t-today?"
}

📌 Character 채팅 로그 불러오기

  • GET /server/rooms/character/{roomId}/logs
    • 설명: 특정 Character 채팅방의 대화 로그를 불러옵니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
    • 응답 예시 
      {
  "status": 200,
  "logs": {
    "id": "e44e4840-d779-49f4-92a6-a289e89d25fc",
    "character_idx": 1,
    "value": [
      {
        "index": 1,
        "img_url": "https://lh3.googleusercontent.com/d/1vSbyd-ANS65Ms0BnMHGdYhzcCpmCYJkV=s220?authuser=0",
        "input_data": "hi, what's your name?",
        "output_data": "G-g-good…b-blessings! I-I’m Rachel. It’s n-nice to m-meet you! How can I h-help you t-today?",
        "timestamp": "2025-03-24 18:26:24"
      }
    ]
  }
}

📌 Character 채팅 로그 수정

  • PUT /server/rooms/character/{roomId}/logs
    • 설명: 기존 Character 채팅 로그의 최신 부분을 수정합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
    • 요청 본문 
      {
  "input_data_set": "안녕하세요?",
  "route_set": "gpt4o_mini"
}
      필드명 타입 필수 설명
      input_data_set string 필수 수정할 사용자 입력 문장
      route_set string 필수 사용할 AI 모델 종류
    • 응답 예시 
      {
  "status": 200,
  "message": "채팅 로그가 성공적으로 수정되었습니다.",
  "response": {
    "Result": "Successfully added data to document with ID: 29e230b3-f03c-4e3e-8ea4-5535323d9801, Values:1"
  }
}

📌 Character 채팅 로그 삭제

  • DELETE /server/rooms/character/{roomId}/logs/{logIndex}
    • 설명: 특정 Character 채팅 로그를 삭제합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      roomId 채팅방 ID
      logIndex 삭제할 로그 인덱스
    • 응답 예시 
      {
  "status": 200,
  "message": "해당 로그가 성공적으로 삭제되었습니다.",
  "response": {
    "Result": "Successfully removed data from index: 1 to the end in document with ID: e44e4840-d779-49f4-92a6-a289e89d25fc"
  }
}

🛠 응답 구조 및 오류 처리

일반 응답

  • 정상 응답: HTTP 상태 코드 200과 함께 요청에 대한 성공 응답 데이터 제공
  • 오류 응답: HTTP 상태 코드와 함께 오류 상세 정보 제공

주요 오류 코드

  • 400: Bad Request - 잘못된 요청 형식 또는 필요한 데이터 누락
  • 401: Unauthorized - 인증 실패 또는 토큰 없음
  • 403: Forbidden - 접근 권한 없음
  • 404: Not Found - 요청한 리소스를 찾을 수 없음
  • 500: Internal Server Error - 서버 내부 오류

📑 특이사항

  • 인증 필수: 모든 API는 Authorization 헤더를 통한 토큰 인증이 필요합니다.
  • 멤버십 정책: 기본(BASIC) 멤버십 사용자는 Llama 모델만 사용 가능하며, VIP 멤버십 사용자는 모든 모델 사용 가능합니다.
  • 데이터 저장: 채팅 로그는 MongoDB에 저장되며, 채팅방 정보는 MySQL에 저장됩니다.
  • Office 모드: 일반적인 정보 제공 기능에 특화된 모드입니다.
  • Character 모드: 특정 캐릭터의 페르소나를 기반으로 대화하는 모드입니다.
  • 검색 기능: Office 모드에서는 google_access_set 매개변수를 통해 검색 결과를 응답에 통합할 수 있습니다.

SpringBoot UserController 명세서

📢 개요

  • API 이름: UserController
  • 설명: 사용자 인증, 회원가입, 정보 관리, 소셜 로그인, 이메일 인증 등 사용자 관련 기능 제공

📍 엔드포인트 목록

🔹 회원가입 및 로그인

📌 회원가입

  • POST /server/user/register
    • 설명: 새로운 사용자를 등록합니다.
    • 요청 본문 
      {
  "name": "test",
  "id": "test1234",
  "email": "test@example.com",
  "pw": "1234",
  "privacy_policy": "true",
  "terms_of_service": "true"
}
      필드명 타입 필수 설명
      name string 예 사용자 이름
      id string 예 사용자 ID
      email string 예 이메일
      pw string 예 비밀번호
      privacy_policy boolean 예 개인정보 처리 동의
      terms_of_service boolean 예 서비스 이용약관 동의
    • 응답 예시 
      {
  "status": 200,
  "token": "jwt-token",
  "name": "test"
}

📌 일반 로그인

  • POST /server/user/login
    • 설명: ID와 비밀번호로 로그인합니다.
    • 요청 본문 
      {
  "id": "test1234",
  "pw": "1234"
}
      필드명 타입 필수 설명
      id string 예 사용자 ID
      pw string 예 비밀번호
    • 응답 예시 
      {
  "token": "jwt-token",
  "name": "홍길동"
}

📌 회원 탈퇴

  • DELETE /server/user/delete/{userid}
    • 설명: 지정한 사용자를 삭제합니다.
    • 경로 매개변수
      매개변수 설명
      userid 사용자 ID
    • 응답 예시 
      {
  "status": 200,
  "message": "User deleted successfully"
}

🔹 소셜 로그인

📌 카카오 소셜 로그인

  • POST /server/user/social/kakao/login
    • 설명: 카카오 인가 코드로 소셜 로그인을 처리합니다.
    • 요청 본문 
      {
  "code": "kakao_auth_code",
  "redirect_uri":
}
      필드명 타입 필수 설명
      code string 예 카카오 인가 코드
    • 응답 예시 
      {
  "status": 200,
  "token": "jwt-token",
  "message": "카카오 로그인 성공"
}

📌 카카오 OAuth 콜백

  • GET /server/user/oauth/callback/kakao?code=...
    • 설명: 카카오 인가 코드 콜백 처리 (프론트에서 직접 호출 시 사용)
    • 응답 예시: 위와 동일

📌 구글 소셜 로그인

  • POST /server/user/social/google/login
    • 설명: 구글 인가 코드로 소셜 로그인을 처리합니다.
    • 요청 본문 
      {
  "code": "google_auth_code",
  "redirect_uri": "https://treenut.ddns.net/server/oauth/callback/google"
}
      필드명 타입 필수 설명
      code string 예 구글 인가 코드
      redirect_uri string 아니오 리다이렉트 URI (선택)
    • 응답 예시 
      {
  "status": 200,
  "token": "jwt-token",
  "message": "구글 로그인 성공"
}

📌 구글 OAuth 콜백

  • GET /server/user/oauth/callback/google?code=...
    • 설명: 구글 인가 코드 콜백 처리 (프론트에서 직접 호출 시 사용)
    • 응답 예시: 위와 동일

🔹 사용자 정보

📌 내 정보 조회

  • GET /server/user/findmyinfo
    • 설명: 토큰 기반으로 내 이름, 아이디, 이메일을 조회합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 예 JWT 인증 토큰
    • 응답 예시 
      {
  "name": "test",
  "userid": "test1234",
  "email": "test@example.com"
}

📌 이름 변경

  • POST /server/user/changeUsername
    • 설명: 사용자 이름을 변경합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 예 JWT 인증 토큰
    • 요청 본문 
      {
  "name": "새이름"
}
      필드명 타입 필수 설명
      name string 예 변경할 이름
    • 응답 예시 
      {
  "status": 200,
  "message": "User information updated successfully"
}

📌 멤버십 조회

  • GET /server/user/membership
    • 설명: 내 멤버십 등급을 조회합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 예 JWT 인증 토큰
    • 응답 예시 
      {
  "status": 200,
  "membership": "멤버십 등급"
}

🔹 이메일 인증

📌 인증 메일 발송

  • POST /server/user/email/Verification
    • 설명: 인증 메일을 발송합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 예 JWT 인증 토큰
    • 요청 본문 
      {
  "email": "test@example.com"
}
      필드명 타입 필수 설명
      email string 예 이메일
    • 응답 예시 
      {
  "status": 200,
  "message": "인증 메일이 발송되었습니다."
}

📌 인증 코드 확인

  • POST /server/user/email/verify-code
    • 설명: 인증 코드를 확인합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 예 JWT 인증 토큰
    • 요청 본문 
      {
  "email": "test@example.com",
  "code": "123456"
}
      필드명 타입 필수 설명
      email string 예 이메일
      code string 예 인증 코드
    • 응답 예시 
      {
  "status": 200,
  "message": "이메일 인증이 완료되었습니다."
}

🛠 응답 구조 및 오류 처리

일반 응답

  • 정상 응답: HTTP 상태 코드 200과 함께 요청에 대한 성공 응답 데이터 제공
  • 오류 응답: HTTP 상태 코드와 함께 오류 상세 정보 제공

주요 오류 코드

  • 400: Bad Request - 잘못된 요청 형식 또는 필요한 데이터 누락
  • 401: Unauthorized - 인증 실패 또는 토큰 없음
  • 403: Forbidden - 접근 권한 없음
  • 404: Not Found - 요청한 리소스를 찾을 수 없음
  • 500: Internal Server Error - 서버 내부 오류

📑 특이사항

  • JWT 인증 필수: 대부분의 API는 Authorization 헤더에 JWT 토큰이 필요합니다.
  • 소셜 로그인: 카카오/구글 인가 코드를 받아 자체 JWT 토큰을 발급합니다.
  • 회원가입 시 약관 동의 필수: privacy_policy, terms_of_service 모두 true여야 가입 가능.
  • 이메일 인증: 이메일 인증 기능 제공(발송/코드 확인).
  • 응답 메시지: status, message, token 등 일관된 구조로 반환.

SpringBoot CharacterController 명세서

📢 개요

  • API 이름: CharacterController
  • 설명: 채팅방 및 대화 관리 API

이 API는 Character 모드의 캐릭터를 저장, 조회, 수정, 삭제하는 기능을 제공합니다.

📍 엔드포인트 목록

🔹 Character CRUD

📌 Character 생성

  • POST /server/character/
    • 설명: 새로운 Character를 생성합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 요청 본문 
        {
  "character_name" : "test",
  "description" : "test characters" ,
  "greeting" : "hello",
  "image" : "https://drive.google.com/thumbnail?id=1a2mPrSRXoPpUCblTO55UXaWsfHlFZK7_",
  "character_setting" : "test setting",
    "access_level" : true
  }
      필드명 타입 필수 설명
      characterName string 필수 생성하려는 캐릭터의 이름
      description string 필수 생성하려는 캐릭터의 설명
      greeting string 필수 생성하려는 캐릭터의 인사말
      image string 필수 생성하려는 캐릭터의 이미지
      character_setting String 필수 생성하려는 캐릭터의 성격
      access_level boolean 필수 생성하려는 캐릭터의 공개여부
    • 응답 예시 
      {
"status": 200,
"name": "test" 
}

📌 Character 수정

  • PUT /server/character/{character_name}
    • 설명: 생성되어 있는 Character를 수정합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      character_name 수정할 캐릭터 이름
    • 요청 본문 
        {
  "character_name" : "test",
  "description" : "test characters" ,
  "greeting" : "hello",
  "image" : "https://drive.google.com/thumbnail?id=1a2mPrSRXoPpUCblTO55UXaWsfHlFZK7_",
  "character_setting" : "test setting",
  "access_level" : true
  }
      필드명 타입 필수 설명
      characterName string 필수 수정하려는 캐릭터의 이름
      description string 필수 수정하려는 캐릭터의 설명
      greeting string 필수 수정하려는 캐릭터의 인사말
      image string 필수 수정하려는 캐릭터의 이미지
      character_setting String 필수 수정하려는 캐릭터의 성격
      access_level boolean 필수 수정하려는 캐릭터의 공개여부
    • 응답 예시 
      {
    "status": 200,
    "message": "Character updated successfully"
}

📌 Character 삭제

  • DELETE /server/character/{character_name}
    • 설명: 생성되어 있는 Character를 삭제합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      character_name 삭제할 캐릭터 이름
    • 응답 예시 
      {
"status": 200,
"message": "Character deleted successfully"
}

📌 Character 조회

  • GET /server/character/public
    • 설명: 공개되어 있는 Character를 조회합니다.
    • 응답 예시 
      {
"status": 200,
"message": "Public characters retrieved successfully",
"data": [
    {
        "characterName": "test",
        "description": "test characters",
        "image": "https://drive.google.com/thumbnail?id=1a2mPrSRXoPpUCblTO55UXaWsfHlFZK7_",
        "creator": "testtest",
        "uuid": "e30c961c48224e58a6ab9e4ae013c3a9",
        "idx": 2
    },
    ...
  ]
}

📌 내 Character 조회

  • GET /server/character/mycharacter
    • 설명: 내 Character를 조회합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 응답 예시 
      {
"status": 200,
"message": "Public characters retrieved successfully",
"data": [
    {
        "characterName": "test",
        "description": "test characters",
        "image": "https://drive.google.com/thumbnail?id=1a2mPrSRXoPpUCblTO55UXaWsfHlFZK7_",
        "creator": "testtest",
        "uuid": "e30c961c48224e58a6ab9e4ae013c3a9",
        "idx": 2
    },
    ...
  ]
}

📌 Character에 좋아요 추가

  • PATCH /server/character/{character_name}/like
    • 설명: Character에 좋아요를 추가합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      character_name 좋아요를 추가할 캐릭터 이름
    • 응답 예시 
      {
"status": 200,
"message": "Like count updated successfully for character: test",
"like_count": 1
}

📌 Character 검색

  • GET /server/character/{character_name}/list
    • 설명: Character를 검색합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      character_name 검색할 캐릭터 이름
    • 응답 예시 
      [
  {
      "character_name": "test11",
      "userid": "test",
      "description": "test characters",
      "image": "https://drive.google.com/thumbnail?id=1a2mPrSRXoPpUCblTO55UXaWsfHlFZK7_"
  },
  ...
]

📌 Character 상세보기(이름)

  • GET /server/character/{character_name}/detail
    • 설명: Character를 이름으로 상세 조회합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      character_name 조회할 캐릭터 이름
    • 응답 예시 
      {
  "character_name": "test",
  "description": "test characters",
  "image": "https://drive.google.com/thumbnail?id=1a2mPrSRXoPpUCblTO55UXaWsfHlFZK7_",
  "userid": "test",
  "like_count": 1
}

📌 Character 상세보기(idx)

  • GET /server/character/idx/{idx}/detail
    • 설명: Character를 이름으로 상세 조회합니다.
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      idx 조회할 캐릭터 idx
    • 응답 예시 
      {
    "idx": 2,
    "uuid": "e30c961c48224e58a6ab9e4ae013c3a9",
    "userid": "test",
    "characterName": "test",
    "characterSetting": "test setting",
    "description": "test characters",
    "greeting": "hello",
    "accessLevel": true,
    "image": "https://drive.google.com/thumbnail?id=1a2mPrSRXoPpUCblTO55UXaWsfHlFZK7_",
    "like_count": 1,
    "liked_users": "test",
    "createdAt": "2025-05-16T14:26:39",
    "updatedAt": "2025-05-16T14:37:20"
}

📌 Character 이미지 업로드

  • POST /server/character/pngimage
    • 설명: Character 이미지 업로드
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • Body (form-data)
      필드명 타입 필수 설명
      file file 필수 업로드할 png 이미지 파일
    • 응답 예시 
      {
  "status": "success",
  "url": "https://lh3.googleusercontent.com/d/1AEE4WJ1oPe4OIma-I7CFTYeatTCoFDCi=s220?authuser=0"
}

📌 Character 공개여부 관리(관리자)

  • GET /server/character/{character_name}/manage/{access_level}
    • 설명: Character 공개여부를 관리합니다(관리자 전용).
    • 헤더
      필드명 타입 필수 설명
      Authorization string 필수 사용자 인증 토큰
    • 경로 매개변수
      매개변수 설명
      character_name 수정할 캐릭터 이름
      access_level 공개여부
    • 응답 예시 
      {
  "status": 200,
  "message": "Character updated successfully"
}
Assets 2
Loading