하나씩 API의 규격을 정리하고 있습니다.

인증된 회원 본인의 정보를 요청하고 응답결과를 아래와 같이 구성해봤습니다.
응답 결과의 각 속성 값은 속성 타입에 따라 swagger에서 생성한 목업 데이터입니다.

{
  "me": {
    "id": "string", // mb_id. 회원 아이디
    "name": "string", // mb_name. 이름
    "displayName": "string", // mb_nick. 닉네임
    "profile": {
      "aboutMe": "string", // mb_profile. 자기소개
      "email": "*** 개인정보보호를 위한 이메일주소 노출방지 ***", // mb_email. 이메일
      "website": "string", // mb_homepage. 홈페이지
      "phone": "string", // mb_tel. 전화번호
      "point": 0, // mb_point. 포인트
      "signature": "string", // mb_signature. 서명
      "iconUrl": "string", // DB에 없음. 회원의 아이콘 이미지 URL
      "pictureUrl": "string", // DB에 없음. 회원의 프로필 이미지 URL
      "open": false, // mb_open. 프로필 공개(정보 공개)
      "openDate": null, // mb_open_data. 프로필 공개 년월일
      "address": {
        "postalCode": "string", // mb_zip1 + mb_zip2. 우편번호
        "addressLine1": "string", // mb_addr1. 주소
        "addressLine2": "string",// mb_addr2
        "addressLine3": "string"// mb_addr3
      }
    },
    "state": {
      "level": 1, // mb_level. 회원 권한 레벨
      "activated": true, // DB에 없음. 회원 계정의 활성화 상태. !blocked && !leaved 그리고 이메일 인증, 본인인증 설정에 따라 verified, certified 까지 확인
      "verified": true, // mb_email_certify. 이메일 인증 여부
      "blocked": false, // mb_intercept_date. 회원 차단 여부. 날짜가 기록되어있으면 true
      "leaved": false, // mb_leave_date. 회원 탈퇴 여부. 날짜가 기록되어있으면 true
      "certified": false, // mb_certify. 본인인증 여부. 기록된 값이 있으면 true
      "adult": true, // mb_adult. 본인인증 당시의 성인 여부
      "messageNewCount": 0, // 읽지않은 쪽지 갯수
      "messageTotalCount": 0, // mb_memo_cnt. 전체 쪽지 갯수 
      "scrapCount": 0 // mb_scrap_cnt. 스크랩 갯수
    },
    "extras": { // 이건 여분 필드들
      "extra1": "string",
      "extra2": "string",
      "extra3": "string",
      "extra4": "string",
      "extra5": "string",
      "extra6": "string",
      "extra7": "string",
      "extra8": "string",
      "extra9": "string",
      "extra10": "string"
    },
    "subscribe": {
      "email": true, // mb_mailling. 이메일 수신 여부
      "sms": true // mb_sms. sms 수신 여부
    },
    "lastLoggedIP": "string", // mb_login_ip. 마지막 로그인 IP
    "createdAt": "2023-04-09T13:12:13.141Z", // mb_datetime. 회원가입일시
    "displayNameUpdatedAt": "2023-04-09T13:12:13.141Z", // mb_nick_date. 닉네임 변경 날짜
    "loggedAt": "2023-04-09T13:12:13.141Z", // mb_today_login. 마지막 로그인 날짜
    "blockedAt": null, // mb_intercept_date. 회원 차단일시
    "leavedAt": null // mb_leave_date. 회원 탈퇴일시
  },
  "_links": { // 관련 리소스 접근에 필요한 URI
    "self": {
      "href": "/me" // 현재 요청. self
    },
    "me": {
      "href": "/me" // /me
    },
    "messages": {
      "href": "/me/messages" // 쪽지 목록
    },
    "scraps": {
      "href": "/me/scraps" // 스크랩 목록
    },
    "points": {
      "href": "/me/points" // 포인트 기록 목록
    }
  }
}

데이터 특징에 따라 몇가지 그룹(profile, state 등)을 만들었고, `mb_` prefix 제거와 좀더 보편적인 이름으로 변경했습니다. id, name, level, point 등 몇가지를 빼고 대부분이 변경되었죠.

굳이 그룹으로 묶은 이유는 특정 그룹의 데이터만 포함, 제외하는 필터로 오버패칭을 피하기위한 방법을 제공하기 위해서입니다. 

결과에 바로 id, name 등의 속성이 나오지 않고 요청한 리소스의 이름... 여기서는 'me'안에 데이터를 담은 이유는 GraphQL 등과의 호환성과 `_links` 등의 부가 데이터 포함, 그리고 `me` 리소스에는 없지만 언더패칭을 개선하기위해 하나의 요청에서 여러 리소스를 수신하기위해서 이런 형태로 만들었습니다.

예를 들면 글 목록을 가져오면서 게시판의 설정 정보나 회원정보를 함께 가져오거나, 글 정보를 요청하면서 댓글 1페이지의 데이터를 함께 가져오는 등의 목적이죠.

REST API에서는 이런 형태는 별도로 데이터를 조합해야하지만 GraphQL에서는 오버패칭과 언더패칭을 해결하기위해 장점으로 내세우는 기본 스펙이기도하죠.

swagger에서는 GraphQL 목업이 불가능해서 postman 같은 다른 툴로 옮겨갈 생각이지만 일단은 OpenAPI 문서로 간단하게 보기에는 swagger가 여전히 유용해서 당분간 이 기반에서 작업할것 같네요.