From 900b9d5b68c740bb2742d74070a805bdce89fc2c Mon Sep 17 00:00:00 2001 From: "kuring.korea@gmail.com" Date: Tue, 21 Jul 2026 19:24:13 +0900 Subject: [PATCH 1/4] =?UTF-8?q?Docs:=20=EC=BA=A0=ED=8D=BC=EC=8A=A4?= =?UTF-8?q?=EB=A7=B5=20API=20=EB=AA=85=EC=84=B8=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Committed by rlagkswn00 on behalf of kuring.korea@gmail.com --- .../campus-map/BuildingDetailResponse.yaml | 94 +++++ .../campus-map/BuildingListResponse.yaml | 32 ++ .../schemas/campus-map/BuildingSummary.yaml | 38 ++ .../schemas/campus-map/CampusPlaceDetail.yaml | 86 ++++ .../schemas/campus-map/CampusPlaceItem.yaml | 95 +++++ .../campus-map/CampusPlaceListResponse.yaml | 56 +++ .../schemas/campus-map/CategoryDto.yaml | 20 + .../campus-map/CategoryListResponse.yaml | 33 ++ .../campus-map/CurrentOperatingHours.yaml | 47 +++ openapi.yaml | 399 +++++++++++++++++- 10 files changed, 897 insertions(+), 3 deletions(-) create mode 100644 components/schemas/campus-map/BuildingDetailResponse.yaml create mode 100644 components/schemas/campus-map/BuildingListResponse.yaml create mode 100644 components/schemas/campus-map/BuildingSummary.yaml create mode 100644 components/schemas/campus-map/CampusPlaceDetail.yaml create mode 100644 components/schemas/campus-map/CampusPlaceItem.yaml create mode 100644 components/schemas/campus-map/CampusPlaceListResponse.yaml create mode 100644 components/schemas/campus-map/CategoryDto.yaml create mode 100644 components/schemas/campus-map/CategoryListResponse.yaml create mode 100644 components/schemas/campus-map/CurrentOperatingHours.yaml diff --git a/components/schemas/campus-map/BuildingDetailResponse.yaml b/components/schemas/campus-map/BuildingDetailResponse.yaml new file mode 100644 index 0000000..e7cc44a --- /dev/null +++ b/components/schemas/campus-map/BuildingDetailResponse.yaml @@ -0,0 +1,94 @@ +type: object +description: 캠퍼스맵 건물 상세 조회 응답의 data +required: + - id + - name + - address + - latitude + - longitude + - imageUrl + - currentOperatingHours + - campusPlaces +properties: + id: + type: integer + format: int64 + description: 건물 ID + example: 4 + name: + type: string + description: 건물명 + example: 학생회관 + address: + type: string + description: 건물 주소 + example: 서울특별시 광진구 능동로 120 + latitude: + type: number + format: double + description: 건물 위도 + example: 37.5412 + longitude: + type: number + format: double + description: 건물 경도 + example: 127.0784 + imageUrl: + type: string + format: uri + nullable: true + description: 건물 이미지 URL. 등록된 이미지가 없으면 null + example: https://placehold.co/1200x800/png?text=Student+Center + currentOperatingHours: + $ref: ./CurrentOperatingHours.yaml + campusPlaces: + type: array + description: 건물에 등록된 주요시설 및 편의시설 목록 + items: + $ref: ./CampusPlaceDetail.yaml +example: + id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5412 + longitude: 127.0784 + imageUrl: https://placehold.co/1200x800/png?text=Student+Center + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + campusPlaces: + - id: 101 + name: 학생회관 편의점 + category: convenience_store + categoryKorName: 편의점 + imageUrl: https://placehold.co/600x400/png?text=Convenience+Store + locationType: INDOOR + floor: 1F + locationDetail: 학생회관 정문 오른쪽 + quantity: null + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + externalUrl: null + - id: 103 + name: 신한은행 학생회관 ATM + category: bank_atm + categoryKorName: 은행·ATM + imageUrl: https://placehold.co/600x400/png?text=ATM + locationType: INDOOR + floor: 1F + locationDetail: 서측 출입구 옆 + quantity: 2 + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: OPEN_24_HOURS + opensAt: null + closesAt: null + externalUrl: null \ No newline at end of file diff --git a/components/schemas/campus-map/BuildingListResponse.yaml b/components/schemas/campus-map/BuildingListResponse.yaml new file mode 100644 index 0000000..89a8b29 --- /dev/null +++ b/components/schemas/campus-map/BuildingListResponse.yaml @@ -0,0 +1,32 @@ +type: object +description: 캠퍼스맵 전체 건물 목록 조회 응답의 data +required: + - buildings +properties: + buildings: + type: array + description: 캠퍼스에 등록된 건물 목록 + items: + $ref: ./BuildingSummary.yaml +example: + buildings: + - id: 1 + name: 행정관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.54241 + longitude: 127.07382 + - id: 2 + name: 경영관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.54196 + longitude: 127.07531 + - id: 3 + name: 법학관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.54174 + longitude: 127.07649 + - id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5412 + longitude: 127.0784 \ No newline at end of file diff --git a/components/schemas/campus-map/BuildingSummary.yaml b/components/schemas/campus-map/BuildingSummary.yaml new file mode 100644 index 0000000..ef5e0fb --- /dev/null +++ b/components/schemas/campus-map/BuildingSummary.yaml @@ -0,0 +1,38 @@ +type: object +description: 캠퍼스맵 건물 요약 정보 +required: + - id + - name + - address + - latitude + - longitude +properties: + id: + type: integer + format: int64 + description: 건물 ID + example: 4 + name: + type: string + description: 건물명 + example: 학생회관 + address: + type: string + description: 건물 주소 + example: 서울특별시 광진구 능동로 120 + latitude: + type: number + format: double + description: 건물 위도 + example: 37.5412 + longitude: + type: number + format: double + description: 건물 경도 + example: 127.0784 +example: + id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5412 + longitude: 127.0784 \ No newline at end of file diff --git a/components/schemas/campus-map/CampusPlaceDetail.yaml b/components/schemas/campus-map/CampusPlaceDetail.yaml new file mode 100644 index 0000000..c3a1561 --- /dev/null +++ b/components/schemas/campus-map/CampusPlaceDetail.yaml @@ -0,0 +1,86 @@ +type: object +description: 건물 상세 화면에 포함되는 시설 정보 +required: + - id + - name + - category + - categoryKorName + - imageUrl + - locationType + - floor + - locationDetail + - quantity + - currentOperatingHours + - externalUrl +properties: + id: + type: integer + format: int64 + description: 시설 ID + example: 102 + name: + type: string + description: 시설명 + example: 학생회관 1층 라운지 프린터 + category: + type: string + description: 카테고리 목록 조회 API에서 제공하는 카테고리 코드 + example: printer + categoryKorName: + type: string + description: 카테고리 한글명 + example: 프린터 + imageUrl: + type: string + format: uri + nullable: true + description: 시설 이미지 URL. 등록된 이미지가 없으면 null + example: https://placehold.co/600x400/png?text=Printer + locationType: + type: string + description: 시설 위치 유형 + enum: + - INDOOR + - OUTDOOR + example: INDOOR + floor: + type: string + description: 시설이 위치한 층. 외부 시설은 OUTDOOR + example: 1F + locationDetail: + type: string + nullable: true + description: 시설의 상세 위치 + example: 라운지 안쪽 + quantity: + type: integer + format: int32 + minimum: 1 + nullable: true + description: 동일 위치에 있는 시설 수량. 수량 개념이 없으면 null + example: 3 + currentOperatingHours: + $ref: ./CurrentOperatingHours.yaml + externalUrl: + type: string + format: uri + nullable: true + description: 시설 관련 외부 페이지 URL. 연결할 페이지가 없으면 null + example: https://wein.konkuk.ac.kr/ +example: + id: 102 + name: 학생회관 1층 라운지 프린터 + category: printer + categoryKorName: 프린터 + imageUrl: https://placehold.co/600x400/png?text=Printer + locationType: INDOOR + floor: 1F + locationDetail: 라운지 안쪽 + quantity: 3 + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + externalUrl: null \ No newline at end of file diff --git a/components/schemas/campus-map/CampusPlaceItem.yaml b/components/schemas/campus-map/CampusPlaceItem.yaml new file mode 100644 index 0000000..7f45384 --- /dev/null +++ b/components/schemas/campus-map/CampusPlaceItem.yaml @@ -0,0 +1,95 @@ +type: object +description: 캠퍼스 건물 내부 또는 외부에 있는 시설 정보 +required: + - id + - name + - category + - categoryKorName + - imageUrl + - locationType + - floor + - locationDetail + - quantity + - currentOperatingHours + - externalUrl + - building +properties: + id: + type: integer + format: int64 + description: 시설 ID + example: 102 + name: + type: string + description: 시설명 + example: 학생회관 1층 라운지 프린터 + category: + type: string + description: 카테고리 목록 조회 API에서 제공하는 카테고리 코드 + example: printer + categoryKorName: + type: string + description: 카테고리 한글명 + example: 프린터 + imageUrl: + type: string + format: uri + nullable: true + description: 시설 이미지 URL. 등록된 이미지가 없으면 null + example: https://placehold.co/600x400/png?text=Printer + locationType: + type: string + description: 시설 위치 유형 + enum: + - INDOOR + - OUTDOOR + example: INDOOR + floor: + type: string + description: 시설이 위치한 층. 외부 시설은 OUTDOOR + example: 1F + locationDetail: + type: string + nullable: true + description: 시설의 상세 위치 + example: 라운지 안쪽 + quantity: + type: integer + format: int32 + minimum: 1 + nullable: true + description: 동일 위치에 있는 시설 수량. 수량 개념이 없으면 null + example: 3 + currentOperatingHours: + $ref: ./CurrentOperatingHours.yaml + externalUrl: + type: string + format: uri + nullable: true + description: 시설 관련 외부 페이지 URL. 연결할 페이지가 없으면 null + example: https://wein.konkuk.ac.kr/ + building: + $ref: ./BuildingSummary.yaml +example: + id: 102 + name: 학생회관 1층 라운지 프린터 + category: printer + categoryKorName: 프린터 + imageUrl: https://placehold.co/600x400/png?text=Printer + locationType: INDOOR + floor: 1F + locationDetail: 라운지 안쪽 + quantity: 3 + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + externalUrl: null + building: + id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5412 + longitude: 127.0784 \ No newline at end of file diff --git a/components/schemas/campus-map/CampusPlaceListResponse.yaml b/components/schemas/campus-map/CampusPlaceListResponse.yaml new file mode 100644 index 0000000..f382caf --- /dev/null +++ b/components/schemas/campus-map/CampusPlaceListResponse.yaml @@ -0,0 +1,56 @@ +type: object +description: 카테고리 기반 시설 목록 조회 응답의 data +required: + - campusPlaces +properties: + campusPlaces: + type: array + description: 요청한 카테고리에 해당하는 시설 목록 + items: + $ref: ./CampusPlaceItem.yaml +example: + campusPlaces: + - id: 102 + name: 학생회관 1층 라운지 프린터 + category: printer + categoryKorName: 프린터 + imageUrl: https://placehold.co/600x400/png?text=Printer + locationType: INDOOR + floor: 1F + locationDetail: 라운지 안쪽 + quantity: 3 + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + externalUrl: null + building: + id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5412 + longitude: 127.0784 + - id: 203 + name: 경영관 지하 1층 프린터 + category: printer + categoryKorName: 프린터 + imageUrl: https://placehold.co/600x400/png?text=Printer + locationType: INDOOR + floor: B1 + locationDetail: 엘리베이터 맞은편 + quantity: 1 + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '21:00' + externalUrl: null + building: + id: 2 + name: 경영관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.54196 + longitude: 127.07531 \ No newline at end of file diff --git a/components/schemas/campus-map/CategoryDto.yaml b/components/schemas/campus-map/CategoryDto.yaml new file mode 100644 index 0000000..7a9a3fb --- /dev/null +++ b/components/schemas/campus-map/CategoryDto.yaml @@ -0,0 +1,20 @@ +type: object +description: 캠퍼스맵 시설 카테고리 정보 +required: + - name + - korName + - displayOrder +properties: + name: + type: string + description: 시설 목록 조회 요청에 사용하는 카테고리 코드 + example: convenience_store + korName: + type: string + description: 클라이언트 화면에 표시할 카테고리 한글명 + example: 편의점 + displayOrder: + type: integer + format: int32 + description: 카테고리 화면 노출 순서 + example: 1 diff --git a/components/schemas/campus-map/CategoryListResponse.yaml b/components/schemas/campus-map/CategoryListResponse.yaml new file mode 100644 index 0000000..db5f43d --- /dev/null +++ b/components/schemas/campus-map/CategoryListResponse.yaml @@ -0,0 +1,33 @@ +type: object +description: 캠퍼스맵 카테고리 목록 조회 응답의 data +required: + - categories +properties: + categories: + type: array + description: 화면 노출 순서로 정렬된 캠퍼스맵 카테고리 목록 + items: + $ref: ./CategoryDto.yaml +example: + categories: + - name: cafe + korName: 카페 + displayOrder: 1 + - name: restaurant + korName: 음식점 + displayOrder: 2 + - name: printer + korName: 프린터 + displayOrder: 3 + - name: smoking_booth + korName: 흡연부스 + displayOrder: 4 + - name: convenience_store + korName: 편의점 + displayOrder: 5 + - name: lounge + korName: 휴게공간 + displayOrder: 6 + - name: kcube + korName: K-Cube + displayOrder: 7 \ No newline at end of file diff --git a/components/schemas/campus-map/CurrentOperatingHours.yaml b/components/schemas/campus-map/CurrentOperatingHours.yaml new file mode 100644 index 0000000..8c246a9 --- /dev/null +++ b/components/schemas/campus-map/CurrentOperatingHours.yaml @@ -0,0 +1,47 @@ +type: object +description: 서버가 현재 날짜를 기준으로 판단한 운영시간 정보 +required: + - period + - dayGroup + - status + - opensAt + - closesAt +properties: + period: + type: string + description: 현재 적용된 운영 기간 + enum: + - SEMESTER + - VACATION + example: SEMESTER + dayGroup: + type: string + description: 현재 적용된 요일 구분 + enum: + - WEEKDAY + - WEEKEND + example: WEEKDAY + status: + type: string + description: 현재 운영시간의 제공 상태 + enum: + - SCHEDULED + - OPEN_24_HOURS + - UNKNOWN + example: SCHEDULED + opensAt: + type: string + nullable: true + description: 운영 시작 시각. OPEN_24_HOURS 또는 UNKNOWN이면 null + example: '08:00' + closesAt: + type: string + nullable: true + description: 운영 종료 시각. OPEN_24_HOURS 또는 UNKNOWN이면 null + example: '22:00' +example: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' \ No newline at end of file diff --git a/openapi.yaml b/openapi.yaml index 3de9ea0..7e3a0f0 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -993,7 +993,7 @@ paths: value: title: 서버 점검 안내 body: 오늘 23시부터 24시까지 서버 점검이 진행됩니다. - url: https://kuring.com/notices/1234 + url: 'https://kuring.com/notices/1234' adminPassword: admin-password responses: '200': @@ -1030,8 +1030,8 @@ paths: value: category: bachelor subject: 테스트 공지입니다 - noticeId: "1234" - articleId: "1234" + noticeId: '1234' + articleId: '1234' responses: '200': description: OK @@ -2086,3 +2086,396 @@ paths: x-stoplight: id: 6qd89rl96a1he description: 사용자가 동아리 구독을 해제합니다. path의 clubId로 대상 동아리를 지정합니다. + /api/v2/maps/categories: + get: + summary: 캠퍼스맵 카테고리 목록 조회 + tags: + - Draft + responses: + '200': + description: 캠퍼스맵 카테고리 목록 조회 성공 + content: + application/json: + schema: + allOf: + - $ref: ./components/schemas/common/BaseResponse.yaml + - type: object + required: + - data + properties: + data: + $ref: ./components/schemas/campus-map/CategoryListResponse.yaml + examples: + Success: + value: + code: 200 + message: 장소 카테고리 목록 조회에 성공하였습니다 + data: + categories: + - name: cafe + korName: 카페 + displayOrder: 1 + - name: restaurant + korName: 음식점 + displayOrder: 2 + - name: printer + korName: 프린터 + displayOrder: 3 + - name: smoking_booth + korName: 흡연부스 + displayOrder: 4 + - name: convenience_store + korName: 편의점 + displayOrder: 5 + - name: lounge + korName: 휴게공간 + displayOrder: 6 + - name: kcube + korName: K-Cube + displayOrder: 7 + operationId: getCampusMapCategories + x-stoplight: + id: nwzexd1chhmmm + description: |- + 캠퍼스맵에서 시설을 필터링할 때 사용하는 카테고리 목록을 조회합니다. + 카테고리는 서버에서 관리하며, 클라이언트는 응답으로 전달된 카테고리 값을 사용합니다. + /api/v2/maps/buildings: + get: + summary: 캠퍼스맵 전체 건물 목록 조회 + tags: + - Draft + responses: + '200': + description: 캠퍼스맵 전체 건물 목록 조회 성공 + content: + application/json: + schema: + allOf: + - $ref: ./components/schemas/common/BaseResponse.yaml + - type: object + required: + - data + properties: + data: + $ref: ./components/schemas/campus-map/BuildingListResponse.yaml + examples: + Success: + value: + code: 200 + message: 캠퍼스 건물 목록 조회에 성공하였습니다 + data: + buildings: + - id: 1 + name: 행정관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.54241 + longitude: 127.07382 + - id: 2 + name: 경영관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.54196 + longitude: 127.07531 + - id: 3 + name: 법학관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.54174 + longitude: 127.07649 + - id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5412 + longitude: 127.0784 + operationId: getCampusMapBuildings + x-stoplight: + id: 9ml6ohwg6sodd + description: |- + 캠퍼스맵 초기 화면에 표시할 전체 건물의 요약 정보를 조회합니다. + 건물 상세 정보와 건물 내부 시설 정보는 포함하지 않습니다. + /api/v2/maps/buildings/search: + get: + summary: 캠퍼스맵 건물 키워드 검색 + tags: + - Draft + responses: + '200': + description: 캠퍼스맵 건물 키워드 검색 성공 + content: + application/json: + schema: + allOf: + - $ref: ./components/schemas/common/BaseResponse.yaml + - type: object + required: + - data + properties: + data: + $ref: ./components/schemas/campus-map/BuildingListResponse.yaml + examples: + Success: + value: + code: 200 + message: 캠퍼스 건물 검색에 성공하였습니다 + data: + buildings: + - id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5412 + longitude: 127.0784 + EmptyResult: + value: + code: 200 + message: 캠퍼스 건물 검색에 성공하였습니다 + data: + buildings: [] + '400': + description: 검색어 누락 또는 잘못된 검색어 + content: + application/json: + schema: + $ref: ./components/schemas/common/ErrorResponse.yaml + examples: + MissingKeyword: + value: + isSuccess: false + resultCode: 400 + resultMsg: 필수 파라미터가 없습니다. + BlankKeyword: + value: + isSuccess: false + resultCode: 400 + resultMsg: 파라미터 값 중 잘못된 값이 있습니다. + operationId: searchCampusMapBuildings + x-stoplight: + id: 4t1enp1xlx2z9 + description: |- + 건물명, 주소 또는 건물에 등록된 검색 키워드를 기준으로 건물을 검색합니다. + 시설명은 검색 대상에 포함하지 않습니다. + parameters: + - schema: + type: string + example: 학관 + minLength: 1 + in: query + name: keyword + required: true + description: 건물명 또는 건물에 등록된 검색 키워드 + /api/v2/maps/campus-places: + get: + summary: 캠퍼스맵 카테고리 기반 시설 목록 조회 + tags: + - Draft + parameters: + - name: categories + in: query + required: true + description: 조회할 시설 카테고리 코드 목록 + style: form + explode: false + schema: + type: array + minItems: 1 + items: + type: string + example: + - printer + - convenience_store + responses: + '200': + description: 카테고리 기반 시설 목록 조회 성공 + content: + application/json: + schema: + allOf: + - $ref: ./components/schemas/common/BaseResponse.yaml + - type: object + required: + - data + properties: + data: + $ref: ./components/schemas/campus-map/CampusPlaceListResponse.yaml + examples: + Success: + value: + code: 200 + message: 카테고리 기반 시설 목록 조회에 성공하였습니다 + data: + campusPlaces: + - id: 101 + name: 학생회관 편의점 + category: convenience_store + categoryKorName: 편의점 + imageUrl: 'https://placehold.co/600x400/png?text=Convenience+Store' + locationType: INDOOR + floor: 1F + locationDetail: 학생회관 정문 오른쪽 + quantity: null + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + externalUrl: null + building: + id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5412 + longitude: 127.0784 + - id: 203 + name: 경영관 지하 1층 프린터 + category: printer + categoryKorName: 프린터 + imageUrl: 'https://placehold.co/600x400/png?text=Printer' + locationType: INDOOR + floor: B1 + locationDetail: 엘리베이터 맞은편 + quantity: 1 + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '21:00' + externalUrl: null + building: + id: 2 + name: 경영관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.54196 + longitude: 127.07531 + EmptyResult: + value: + code: 200 + message: 카테고리 기반 시설 목록 조회에 성공하였습니다 + data: + campusPlaces: [] + '400': + description: 시설 카테고리 파라미터 누락 + content: + application/json: + schema: + $ref: ./components/schemas/common/ErrorResponse.yaml + examples: + MissingCategories: + value: + isSuccess: false + resultCode: 400 + resultMsg: 필수 파라미터가 없습니다. + operationId: getCampusPlacesByCategories + x-stoplight: + id: qg6o2s3rf3cyy + description: |- + 선택한 카테고리에 해당하는 캠퍼스 시설 목록을 조회합니다. + 여러 카테고리는 쉼표로 구분하며, 각 시설에는 소속 건물과 현재 기준 운영시간이 포함됩니다. + '/api/v2/maps/buildings/{buildingId}': + get: + summary: 캠퍼스맵 건물 상세 조회 + tags: + - Draft + parameters: + - name: buildingId + in: path + required: true + description: 조회할 건물 ID + schema: + type: integer + format: int64 + minimum: 1 + example: 4 + responses: + '200': + description: 캠퍼스맵 건물 상세 조회 성공 + content: + application/json: + schema: + allOf: + - $ref: './components/schemas/common/BaseResponse.yaml' + - type: object + required: + - data + properties: + data: + $ref: './components/schemas/campus-map/BuildingDetailResponse.yaml' + examples: + Success: + value: + code: 200 + message: 캠퍼스 건물 상세 조회에 성공하였습니다 + data: + id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5412 + longitude: 127.0784 + imageUrl: https://placehold.co/1200x800/png?text=Student+Center + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + campusPlaces: + - id: 101 + name: 학생회관 편의점 + category: convenience_store + categoryKorName: 편의점 + imageUrl: https://placehold.co/600x400/png?text=Convenience+Store + locationType: INDOOR + floor: 1F + locationDetail: 학생회관 정문 오른쪽 + quantity: null + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + externalUrl: null + - id: 103 + name: 신한은행 학생회관 ATM + category: bank_atm + categoryKorName: 은행·ATM + imageUrl: https://placehold.co/600x400/png?text=ATM + locationType: INDOOR + floor: 1F + locationDetail: 서측 출입구 옆 + quantity: 2 + currentOperatingHours: + period: SEMESTER + dayGroup: WEEKDAY + status: OPEN_24_HOURS + opensAt: null + closesAt: null + externalUrl: null + '400': + description: 건물 ID 형식 오류 + content: + application/json: + schema: + $ref: './components/schemas/common/ErrorResponse.yaml' + examples: + InvalidBuildingId: + value: + isSuccess: false + resultCode: 400 + resultMsg: 파라미터 값 중 잘못된 값이 있습니다. + '404': + description: 건물을 찾을 수 없음 + content: + application/json: + schema: + $ref: './components/schemas/common/BaseResponse.yaml' + examples: + BuildingNotFound: + value: + code: 404 + message: 캠퍼스 건물을 찾을 수 없습니다 + data: null + operationId: getCampusMapBuildingDetail + x-stoplight: + id: 0pp8wii0i7fzx + description: |- + 건물 ID를 기준으로 건물 상세 정보와 건물에 등록된 주요시설 및 편의시설을 조회합니다. + 운영시간은 서버가 현재 날짜를 기준으로 판단한 값만 반환합니다. From 78094cd92c4221080d7eb7753b264cbac24bcda3 Mon Sep 17 00:00:00 2001 From: "kuring.korea@gmail.com" Date: Thu, 30 Jul 2026 15:34:33 +0900 Subject: [PATCH 2/4] =?UTF-8?q?Docs:=20=EC=BA=A0=ED=8D=BC=EC=8A=A4?= =?UTF-8?q?=EB=A7=B5=20API=20=EC=9D=91=EB=8B=B5=20=EA=B5=AC=EC=A1=B0=20?= =?UTF-8?q?=EB=B0=8F=20enum=20=EB=AA=85=EC=84=B8=20=EB=B3=B4=EC=99=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Committed by rlagkswn00 on behalf of kuring.korea@gmail.com --- .../campus-map/BuildingDetailResponse.yaml | 138 ++++++--- .../campus-map/BuildingListResponse.yaml | 26 +- .../schemas/campus-map/BuildingSummary.yaml | 8 +- .../schemas/campus-map/CampusPlaceDetail.yaml | 91 ++++-- .../schemas/campus-map/CampusPlaceItem.yaml | 91 ++++-- .../campus-map/CampusPlaceListResponse.yaml | 100 ++++-- .../schemas/campus-map/CategoryDto.yaml | 19 +- .../campus-map/CategoryListResponse.yaml | 8 +- .../campus-map/CurrentOperatingHours.yaml | 47 --- .../schemas/campus-map/OperatingHoursDto.yaml | 63 ++++ openapi.yaml | 287 +++++++++++++----- 11 files changed, 614 insertions(+), 264 deletions(-) delete mode 100644 components/schemas/campus-map/CurrentOperatingHours.yaml create mode 100644 components/schemas/campus-map/OperatingHoursDto.yaml diff --git a/components/schemas/campus-map/BuildingDetailResponse.yaml b/components/schemas/campus-map/BuildingDetailResponse.yaml index e7cc44a..930bf51 100644 --- a/components/schemas/campus-map/BuildingDetailResponse.yaml +++ b/components/schemas/campus-map/BuildingDetailResponse.yaml @@ -7,7 +7,7 @@ required: - latitude - longitude - imageUrl - - currentOperatingHours + - operatingHours - campusPlaces properties: id: @@ -27,20 +27,23 @@ properties: type: number format: double description: 건물 위도 - example: 37.5412 + example: 37.541823 longitude: type: number format: double description: 건물 경도 - example: 127.0784 + example: 127.0779007 imageUrl: type: string format: uri nullable: true description: 건물 이미지 URL. 등록된 이미지가 없으면 null - example: https://placehold.co/1200x800/png?text=Student+Center - currentOperatingHours: - $ref: ./CurrentOperatingHours.yaml + example: https://placehold.co/1200x800/png?text=Konkuk+University + operatingHours: + type: array + description: 기간·요일별 전체 운영시간. 배열 순서와 관계없이 isCurrent가 true인 항목이 현재 적용되는 운영시간 + items: + $ref: ./OperatingHoursDto.yaml campusPlaces: type: array description: 건물에 등록된 주요시설 및 편의시설 목록 @@ -50,45 +53,102 @@ example: id: 4 name: 학생회관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5412 - longitude: 127.0784 - imageUrl: https://placehold.co/1200x800/png?text=Student+Center - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '08:00' - closesAt: '22:00' + latitude: 37.541823 + longitude: 127.0779007 + imageUrl: https://placehold.co/1200x800/png?text=Konkuk+University + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false campusPlaces: - - id: 101 - name: 학생회관 편의점 - category: convenience_store - categoryKorName: 편의점 - imageUrl: https://placehold.co/600x400/png?text=Convenience+Store + - id: 402 + name: 학생회관 복사실 + category: printer + categoryKorName: 프린터 + imageUrl: https://placehold.co/600x400/png?text=Printer locationType: INDOOR floor: 1F - locationDetail: 학생회관 정문 오른쪽 - quantity: null - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '08:00' - closesAt: '22:00' + locationDetail: 학생회관 1층 + quantity: 2 + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false externalUrl: null - - id: 103 - name: 신한은행 학생회관 ATM + - id: 406 + name: 신한은행 category: bank_atm categoryKorName: 은행·ATM imageUrl: https://placehold.co/600x400/png?text=ATM locationType: INDOOR floor: 1F - locationDetail: 서측 출입구 옆 - quantity: 2 - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: OPEN_24_HOURS - opensAt: null - closesAt: null - externalUrl: null \ No newline at end of file + locationDetail: 학생회관 1층 + quantity: null + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false + externalUrl: null diff --git a/components/schemas/campus-map/BuildingListResponse.yaml b/components/schemas/campus-map/BuildingListResponse.yaml index 89a8b29..1832ed6 100644 --- a/components/schemas/campus-map/BuildingListResponse.yaml +++ b/components/schemas/campus-map/BuildingListResponse.yaml @@ -13,20 +13,30 @@ example: - id: 1 name: 행정관 address: 서울특별시 광진구 능동로 120 - latitude: 37.54241 - longitude: 127.07382 + latitude: 37.5444801 + longitude: 127.0748518 - id: 2 name: 경영관 address: 서울특별시 광진구 능동로 120 - latitude: 37.54196 - longitude: 127.07531 + latitude: 37.5443474 + longitude: 127.0761119 - id: 3 name: 법학관 address: 서울특별시 광진구 능동로 120 - latitude: 37.54174 - longitude: 127.07649 + latitude: 37.5417036 + longitude: 127.0750767 - id: 4 name: 학생회관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5412 - longitude: 127.0784 \ No newline at end of file + latitude: 37.541823 + longitude: 127.0779007 + - id: 10 + name: 상허기념도서관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5420474 + longitude: 127.0738384 + - id: 20 + name: 과학관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.541467 + longitude: 127.0805824 diff --git a/components/schemas/campus-map/BuildingSummary.yaml b/components/schemas/campus-map/BuildingSummary.yaml index ef5e0fb..a5d2456 100644 --- a/components/schemas/campus-map/BuildingSummary.yaml +++ b/components/schemas/campus-map/BuildingSummary.yaml @@ -24,15 +24,15 @@ properties: type: number format: double description: 건물 위도 - example: 37.5412 + example: 37.541823 longitude: type: number format: double description: 건물 경도 - example: 127.0784 + example: 127.0779007 example: id: 4 name: 학생회관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5412 - longitude: 127.0784 \ No newline at end of file + latitude: 37.541823 + longitude: 127.0779007 diff --git a/components/schemas/campus-map/CampusPlaceDetail.yaml b/components/schemas/campus-map/CampusPlaceDetail.yaml index c3a1561..c5459c5 100644 --- a/components/schemas/campus-map/CampusPlaceDetail.yaml +++ b/components/schemas/campus-map/CampusPlaceDetail.yaml @@ -10,25 +10,45 @@ required: - floor - locationDetail - quantity - - currentOperatingHours + - operatingHours - externalUrl properties: id: type: integer format: int64 description: 시설 ID - example: 102 + example: 301 name: type: string description: 시설명 - example: 학생회관 1층 라운지 프린터 + example: 법학관 인쇄소 category: type: string - description: 카테고리 목록 조회 API에서 제공하는 카테고리 코드 + description: |- + 시설 카테고리 코드입니다. 건물 상세 조회에서는 시설 필터에 노출되는 7종 외에 내부 카테고리도 반환될 수 있습니다. + - `cafe`: 카페 + - `restaurant`: 식당 + - `printer`: 프린터 + - `smoking_booth`: 흡연부스 + - `convenience_store`: 편의점 + - `lounge`: 휴게실 + - `kcube`: KCUBE + - `bank_atm`: 은행·ATM + - `post_office`: 우체국 + enum: + - cafe + - restaurant + - printer + - smoking_booth + - convenience_store + - lounge + - kcube + - bank_atm + - post_office example: printer categoryKorName: type: string - description: 카테고리 한글명 + description: 클라이언트 화면에 표시할 카테고리 한글명 example: 프린터 imageUrl: type: string @@ -38,7 +58,10 @@ properties: example: https://placehold.co/600x400/png?text=Printer locationType: type: string - description: 시설 위치 유형 + description: |- + 시설 위치 유형입니다. + - `INDOOR`: 건물 내부 + - `OUTDOOR`: 건물 외부 enum: - INDOOR - OUTDOOR @@ -46,21 +69,24 @@ properties: floor: type: string description: 시설이 위치한 층. 외부 시설은 OUTDOOR - example: 1F + example: B1 locationDetail: type: string nullable: true description: 시설의 상세 위치 - example: 라운지 안쪽 + example: 법학관 지하 1층 quantity: type: integer format: int32 minimum: 1 nullable: true description: 동일 위치에 있는 시설 수량. 수량 개념이 없으면 null - example: 3 - currentOperatingHours: - $ref: ./CurrentOperatingHours.yaml + example: 1 + operatingHours: + type: array + description: 기간·요일별 전체 운영시간. 배열 순서와 관계없이 isCurrent가 true인 항목이 현재 적용되는 운영시간 + items: + $ref: ./OperatingHoursDto.yaml externalUrl: type: string format: uri @@ -68,19 +94,38 @@ properties: description: 시설 관련 외부 페이지 URL. 연결할 페이지가 없으면 null example: https://wein.konkuk.ac.kr/ example: - id: 102 - name: 학생회관 1층 라운지 프린터 + id: 301 + name: 법학관 인쇄소 category: printer categoryKorName: 프린터 imageUrl: https://placehold.co/600x400/png?text=Printer locationType: INDOOR - floor: 1F - locationDetail: 라운지 안쪽 - quantity: 3 - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '08:00' - closesAt: '22:00' - externalUrl: null \ No newline at end of file + floor: B1 + locationDetail: 법학관 지하 1층 + quantity: 1 + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false + externalUrl: null diff --git a/components/schemas/campus-map/CampusPlaceItem.yaml b/components/schemas/campus-map/CampusPlaceItem.yaml index 7f45384..a09602c 100644 --- a/components/schemas/campus-map/CampusPlaceItem.yaml +++ b/components/schemas/campus-map/CampusPlaceItem.yaml @@ -10,7 +10,7 @@ required: - floor - locationDetail - quantity - - currentOperatingHours + - operatingHours - externalUrl - building properties: @@ -18,14 +18,30 @@ properties: type: integer format: int64 description: 시설 ID - example: 102 + example: 301 name: type: string description: 시설명 - example: 학생회관 1층 라운지 프린터 + example: 법학관 인쇄소 category: type: string - description: 카테고리 목록 조회 API에서 제공하는 카테고리 코드 + description: |- + 카테고리 목록 조회 API에서 제공하는 시설 필터 코드입니다. + - `cafe`: 카페 + - `restaurant`: 식당 + - `printer`: 프린터 + - `smoking_booth`: 흡연부스 + - `convenience_store`: 편의점 + - `lounge`: 휴게실 + - `kcube`: KCUBE + enum: + - cafe + - restaurant + - printer + - smoking_booth + - convenience_store + - lounge + - kcube example: printer categoryKorName: type: string @@ -39,7 +55,10 @@ properties: example: https://placehold.co/600x400/png?text=Printer locationType: type: string - description: 시설 위치 유형 + description: |- + 시설 위치 유형입니다. + - `INDOOR`: 건물 내부 + - `OUTDOOR`: 건물 외부 enum: - INDOOR - OUTDOOR @@ -47,21 +66,24 @@ properties: floor: type: string description: 시설이 위치한 층. 외부 시설은 OUTDOOR - example: 1F + example: B1 locationDetail: type: string nullable: true description: 시설의 상세 위치 - example: 라운지 안쪽 + example: 법학관 지하 1층 quantity: type: integer format: int32 minimum: 1 nullable: true description: 동일 위치에 있는 시설 수량. 수량 개념이 없으면 null - example: 3 - currentOperatingHours: - $ref: ./CurrentOperatingHours.yaml + example: 1 + operatingHours: + type: array + description: 기간·요일별 전체 운영시간. 배열 순서와 관계없이 isCurrent가 true인 항목이 현재 적용되는 운영시간 + items: + $ref: ./OperatingHoursDto.yaml externalUrl: type: string format: uri @@ -71,25 +93,44 @@ properties: building: $ref: ./BuildingSummary.yaml example: - id: 102 - name: 학생회관 1층 라운지 프린터 + id: 301 + name: 법학관 인쇄소 category: printer categoryKorName: 프린터 imageUrl: https://placehold.co/600x400/png?text=Printer locationType: INDOOR - floor: 1F - locationDetail: 라운지 안쪽 - quantity: 3 - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '08:00' - closesAt: '22:00' + floor: B1 + locationDetail: 법학관 지하 1층 + quantity: 1 + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false externalUrl: null building: - id: 4 - name: 학생회관 + id: 3 + name: 법학관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5412 - longitude: 127.0784 \ No newline at end of file + latitude: 37.5417036 + longitude: 127.0750767 diff --git a/components/schemas/campus-map/CampusPlaceListResponse.yaml b/components/schemas/campus-map/CampusPlaceListResponse.yaml index f382caf..f216a74 100644 --- a/components/schemas/campus-map/CampusPlaceListResponse.yaml +++ b/components/schemas/campus-map/CampusPlaceListResponse.yaml @@ -10,47 +10,85 @@ properties: $ref: ./CampusPlaceItem.yaml example: campusPlaces: - - id: 102 - name: 학생회관 1층 라운지 프린터 + - id: 301 + name: 법학관 인쇄소 category: printer categoryKorName: 프린터 imageUrl: https://placehold.co/600x400/png?text=Printer locationType: INDOOR - floor: 1F - locationDetail: 라운지 안쪽 - quantity: 3 - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '08:00' - closesAt: '22:00' + floor: B1 + locationDetail: 법학관 지하 1층 + quantity: 1 + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false externalUrl: null building: - id: 4 - name: 학생회관 + id: 3 + name: 법학관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5412 - longitude: 127.0784 - - id: 203 - name: 경영관 지하 1층 프린터 - category: printer - categoryKorName: 프린터 - imageUrl: https://placehold.co/600x400/png?text=Printer - locationType: INDOOR - floor: B1 - locationDetail: 엘리베이터 맞은편 + latitude: 37.5417036 + longitude: 127.0750767 + - id: 205 + name: 경영관 흡연부스 + category: smoking_booth + categoryKorName: 흡연부스 + imageUrl: https://placehold.co/600x400/png?text=Smoking+Booth + locationType: OUTDOOR + floor: OUTDOOR + locationDetail: 경영관 CU 앞 quantity: 1 - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '09:00' - closesAt: '21:00' + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: OPEN_24_HOURS + opensAt: null + closesAt: null + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: OPEN_24_HOURS + opensAt: null + closesAt: null + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: OPEN_24_HOURS + opensAt: null + closesAt: null + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: OPEN_24_HOURS + opensAt: null + closesAt: null + isCurrent: false externalUrl: null building: id: 2 name: 경영관 address: 서울특별시 광진구 능동로 120 - latitude: 37.54196 - longitude: 127.07531 \ No newline at end of file + latitude: 37.5443474 + longitude: 127.0761119 diff --git a/components/schemas/campus-map/CategoryDto.yaml b/components/schemas/campus-map/CategoryDto.yaml index 7a9a3fb..2e06acd 100644 --- a/components/schemas/campus-map/CategoryDto.yaml +++ b/components/schemas/campus-map/CategoryDto.yaml @@ -7,7 +7,23 @@ required: properties: name: type: string - description: 시설 목록 조회 요청에 사용하는 카테고리 코드 + description: |- + 시설 목록 조회 요청에 사용하는 카테고리 코드입니다. + - `cafe`: 카페 + - `restaurant`: 식당 + - `printer`: 프린터 + - `smoking_booth`: 흡연부스 + - `convenience_store`: 편의점 + - `lounge`: 휴게실 + - `kcube`: KCUBE + enum: + - cafe + - restaurant + - printer + - smoking_booth + - convenience_store + - lounge + - kcube example: convenience_store korName: type: string @@ -16,5 +32,6 @@ properties: displayOrder: type: integer format: int32 + minimum: 1 description: 카테고리 화면 노출 순서 example: 1 diff --git a/components/schemas/campus-map/CategoryListResponse.yaml b/components/schemas/campus-map/CategoryListResponse.yaml index db5f43d..a5e08f4 100644 --- a/components/schemas/campus-map/CategoryListResponse.yaml +++ b/components/schemas/campus-map/CategoryListResponse.yaml @@ -14,7 +14,7 @@ example: korName: 카페 displayOrder: 1 - name: restaurant - korName: 음식점 + korName: 식당 displayOrder: 2 - name: printer korName: 프린터 @@ -26,8 +26,8 @@ example: korName: 편의점 displayOrder: 5 - name: lounge - korName: 휴게공간 + korName: 휴게실 displayOrder: 6 - name: kcube - korName: K-Cube - displayOrder: 7 \ No newline at end of file + korName: KCUBE + displayOrder: 7 diff --git a/components/schemas/campus-map/CurrentOperatingHours.yaml b/components/schemas/campus-map/CurrentOperatingHours.yaml deleted file mode 100644 index 8c246a9..0000000 --- a/components/schemas/campus-map/CurrentOperatingHours.yaml +++ /dev/null @@ -1,47 +0,0 @@ -type: object -description: 서버가 현재 날짜를 기준으로 판단한 운영시간 정보 -required: - - period - - dayGroup - - status - - opensAt - - closesAt -properties: - period: - type: string - description: 현재 적용된 운영 기간 - enum: - - SEMESTER - - VACATION - example: SEMESTER - dayGroup: - type: string - description: 현재 적용된 요일 구분 - enum: - - WEEKDAY - - WEEKEND - example: WEEKDAY - status: - type: string - description: 현재 운영시간의 제공 상태 - enum: - - SCHEDULED - - OPEN_24_HOURS - - UNKNOWN - example: SCHEDULED - opensAt: - type: string - nullable: true - description: 운영 시작 시각. OPEN_24_HOURS 또는 UNKNOWN이면 null - example: '08:00' - closesAt: - type: string - nullable: true - description: 운영 종료 시각. OPEN_24_HOURS 또는 UNKNOWN이면 null - example: '22:00' -example: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '08:00' - closesAt: '22:00' \ No newline at end of file diff --git a/components/schemas/campus-map/OperatingHoursDto.yaml b/components/schemas/campus-map/OperatingHoursDto.yaml new file mode 100644 index 0000000..2194389 --- /dev/null +++ b/components/schemas/campus-map/OperatingHoursDto.yaml @@ -0,0 +1,63 @@ +type: object +description: 시설 또는 건물에 등록된 기간·요일별 운영시간 +example: + period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true +required: + - period + - dayGroup + - status + - opensAt + - closesAt + - isCurrent +properties: + period: + type: string + description: |- + 운영 기간 구분입니다. + - `SEMESTER`: 학기 중 + - `VACATION`: 방학 중 + enum: + - SEMESTER + - VACATION + example: VACATION + dayGroup: + type: string + description: |- + 운영 요일 구분입니다. + - `WEEKDAY`: 주중(월요일~금요일) + - `WEEKEND`: 주말(토요일~일요일) + enum: + - WEEKDAY + - WEEKEND + example: WEEKDAY + status: + type: string + description: |- + 해당 운영시간의 제공 상태입니다. + - `SCHEDULED`: 정해진 운영시간이 있으며 opensAt과 closesAt을 함께 사용 + - `OPEN_24_HOURS`: 24시간 운영하며 opensAt과 closesAt은 null + - `UNKNOWN`: 운영시간 정보가 없으며 opensAt과 closesAt은 null + enum: + - SCHEDULED + - OPEN_24_HOURS + - UNKNOWN + example: SCHEDULED + opensAt: + type: string + nullable: true + description: '운영 시작 시각(HH:mm). SCHEDULED가 아니면 null' + example: '09:00' + closesAt: + type: string + nullable: true + description: '운영 종료 시각(HH:mm). SCHEDULED가 아니면 null' + example: '18:00' + isCurrent: + type: boolean + description: 서버가 현재 날짜를 기준으로 판단한 운영시간인지 여부 + example: true diff --git a/openapi.yaml b/openapi.yaml index 7e3a0f0..ad0f377 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2116,7 +2116,7 @@ paths: korName: 카페 displayOrder: 1 - name: restaurant - korName: 음식점 + korName: 식당 displayOrder: 2 - name: printer korName: 프린터 @@ -2128,10 +2128,10 @@ paths: korName: 편의점 displayOrder: 5 - name: lounge - korName: 휴게공간 + korName: 휴게실 displayOrder: 6 - name: kcube - korName: K-Cube + korName: KCUBE displayOrder: 7 operationId: getCampusMapCategories x-stoplight: @@ -2168,23 +2168,33 @@ paths: - id: 1 name: 행정관 address: 서울특별시 광진구 능동로 120 - latitude: 37.54241 - longitude: 127.07382 + latitude: 37.5444801 + longitude: 127.0748518 - id: 2 name: 경영관 address: 서울특별시 광진구 능동로 120 - latitude: 37.54196 - longitude: 127.07531 + latitude: 37.5443474 + longitude: 127.0761119 - id: 3 name: 법학관 address: 서울특별시 광진구 능동로 120 - latitude: 37.54174 - longitude: 127.07649 + latitude: 37.5417036 + longitude: 127.0750767 - id: 4 name: 학생회관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5412 - longitude: 127.0784 + latitude: 37.541823 + longitude: 127.0779007 + - id: 10 + name: 상허기념도서관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5420474 + longitude: 127.0738384 + - id: 20 + name: 과학관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.541467 + longitude: 127.0805824 operationId: getCampusMapBuildings x-stoplight: id: 9ml6ohwg6sodd @@ -2220,8 +2230,8 @@ paths: - id: 4 name: 학생회관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5412 - longitude: 127.0784 + latitude: 37.541823 + longitude: 127.0779007 EmptyResult: value: code: 200 @@ -2277,9 +2287,26 @@ paths: minItems: 1 items: type: string + description: |- + 조회할 시설 카테고리 코드입니다. + - `cafe`: 카페 + - `restaurant`: 식당 + - `printer`: 프린터 + - `smoking_booth`: 흡연부스 + - `convenience_store`: 편의점 + - `lounge`: 휴게실 + - `kcube`: KCUBE + enum: + - cafe + - restaurant + - printer + - smoking_booth + - convenience_store + - lounge + - kcube example: - printer - - convenience_store + - smoking_booth responses: '200': description: 카테고리 기반 시설 목록 조회 성공 @@ -2301,50 +2328,88 @@ paths: message: 카테고리 기반 시설 목록 조회에 성공하였습니다 data: campusPlaces: - - id: 101 - name: 학생회관 편의점 - category: convenience_store - categoryKorName: 편의점 - imageUrl: 'https://placehold.co/600x400/png?text=Convenience+Store' - locationType: INDOOR - floor: 1F - locationDetail: 학생회관 정문 오른쪽 - quantity: null - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '08:00' - closesAt: '22:00' - externalUrl: null - building: - id: 4 - name: 학생회관 - address: 서울특별시 광진구 능동로 120 - latitude: 37.5412 - longitude: 127.0784 - - id: 203 - name: 경영관 지하 1층 프린터 + - id: 301 + name: 법학관 인쇄소 category: printer categoryKorName: 프린터 imageUrl: 'https://placehold.co/600x400/png?text=Printer' locationType: INDOOR floor: B1 - locationDetail: 엘리베이터 맞은편 + locationDetail: 법학관 지하 1층 + quantity: 1 + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false + externalUrl: null + building: + id: 3 + name: 법학관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5417036 + longitude: 127.0750767 + - id: 205 + name: 경영관 흡연부스 + category: smoking_booth + categoryKorName: 흡연부스 + imageUrl: 'https://placehold.co/600x400/png?text=Smoking+Booth' + locationType: OUTDOOR + floor: OUTDOOR + locationDetail: 경영관 CU 앞 quantity: 1 - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '09:00' - closesAt: '21:00' + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: OPEN_24_HOURS + opensAt: null + closesAt: null + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: OPEN_24_HOURS + opensAt: null + closesAt: null + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: OPEN_24_HOURS + opensAt: null + closesAt: null + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: OPEN_24_HOURS + opensAt: null + closesAt: null + isCurrent: false externalUrl: null building: id: 2 name: 경영관 address: 서울특별시 광진구 능동로 120 - latitude: 37.54196 - longitude: 127.07531 + latitude: 37.5443474 + longitude: 127.0761119 EmptyResult: value: code: 200 @@ -2367,8 +2432,9 @@ paths: x-stoplight: id: qg6o2s3rf3cyy description: |- - 선택한 카테고리에 해당하는 캠퍼스 시설 목록을 조회합니다. - 여러 카테고리는 쉼표로 구분하며, 각 시설에는 소속 건물과 현재 기준 운영시간이 포함됩니다. + 선택한 카테고리 중 하나 이상에 해당하는 캠퍼스 시설 목록을 조회합니다. + 여러 카테고리는 쉼표로 구분하며 OR 조건으로 조회합니다. + 각 시설에는 소속 건물과 기간·요일별 전체 운영시간이 포함되며, 현재 적용되는 운영시간은 isCurrent로 구분합니다. '/api/v2/maps/buildings/{buildingId}': get: summary: 캠퍼스맵 건물 상세 조회 @@ -2407,47 +2473,104 @@ paths: id: 4 name: 학생회관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5412 - longitude: 127.0784 - imageUrl: https://placehold.co/1200x800/png?text=Student+Center - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '08:00' - closesAt: '22:00' + latitude: 37.541823 + longitude: 127.0779007 + imageUrl: https://placehold.co/1200x800/png?text=Konkuk+University + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false campusPlaces: - - id: 101 - name: 학생회관 편의점 - category: convenience_store - categoryKorName: 편의점 - imageUrl: https://placehold.co/600x400/png?text=Convenience+Store + - id: 402 + name: 학생회관 복사실 + category: printer + categoryKorName: 프린터 + imageUrl: https://placehold.co/600x400/png?text=Printer locationType: INDOOR floor: 1F - locationDetail: 학생회관 정문 오른쪽 - quantity: null - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: SCHEDULED - opensAt: '08:00' - closesAt: '22:00' + locationDetail: 학생회관 1층 + quantity: 2 + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false externalUrl: null - - id: 103 - name: 신한은행 학생회관 ATM + - id: 406 + name: 신한은행 category: bank_atm categoryKorName: 은행·ATM imageUrl: https://placehold.co/600x400/png?text=ATM locationType: INDOOR floor: 1F - locationDetail: 서측 출입구 옆 - quantity: 2 - currentOperatingHours: - period: SEMESTER - dayGroup: WEEKDAY - status: OPEN_24_HOURS - opensAt: null - closesAt: null + locationDetail: 학생회관 1층 + quantity: null + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: false + - period: SEMESTER + dayGroup: WEEKEND + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: true + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false externalUrl: null '400': description: 건물 ID 형식 오류 @@ -2478,4 +2601,4 @@ paths: id: 0pp8wii0i7fzx description: |- 건물 ID를 기준으로 건물 상세 정보와 건물에 등록된 주요시설 및 편의시설을 조회합니다. - 운영시간은 서버가 현재 날짜를 기준으로 판단한 값만 반환합니다. + 건물과 시설의 기간·요일별 전체 운영시간을 반환하며, 현재 적용되는 운영시간은 isCurrent가 true입니다. From 4a1bb5175ad86ade3ae9ea3be7e775c34a40a21d Mon Sep 17 00:00:00 2001 From: "kuring.korea@gmail.com" Date: Wed, 12 Aug 2026 03:35:09 +0900 Subject: [PATCH 3/4] =?UTF-8?q?Docs:=20=EC=BA=A0=ED=8D=BC=EC=8A=A4?= =?UTF-8?q?=EB=A7=B5=20=EA=B2=80=EC=83=89=20=EB=B0=8F=20=EC=9D=91=EB=8B=B5?= =?UTF-8?q?=20=EB=AA=85=EC=84=B8=20=EB=B3=B4=EC=99=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Committed by rlagkswn00 on behalf of kuring.korea@gmail.com --- .../campus-map/BuildingDetailResponse.yaml | 8 +- .../campus-map/BuildingListResponse.yaml | 8 +- .../schemas/campus-map/BuildingOverview.yaml | 40 ++++++++ .../campus-map/CampusMapSearchResponse.yaml | 65 ++++++++++++ .../schemas/campus-map/CampusPlaceDetail.yaml | 12 +-- .../schemas/campus-map/CampusPlaceItem.yaml | 12 +-- .../campus-map/CampusPlaceListResponse.yaml | 4 +- .../schemas/campus-map/CategoryDto.yaml | 2 +- .../campus-map/CategoryListResponse.yaml | 4 +- openapi.yaml | 98 ++++++++++++++----- 10 files changed, 207 insertions(+), 46 deletions(-) create mode 100644 components/schemas/campus-map/BuildingOverview.yaml create mode 100644 components/schemas/campus-map/CampusMapSearchResponse.yaml diff --git a/components/schemas/campus-map/BuildingDetailResponse.yaml b/components/schemas/campus-map/BuildingDetailResponse.yaml index 930bf51..3c81be0 100644 --- a/components/schemas/campus-map/BuildingDetailResponse.yaml +++ b/components/schemas/campus-map/BuildingDetailResponse.yaml @@ -38,7 +38,7 @@ properties: format: uri nullable: true description: 건물 이미지 URL. 등록된 이미지가 없으면 null - example: https://placehold.co/1200x800/png?text=Konkuk+University + example: https://placehold.co/1200x800/png?text=Student+Center operatingHours: type: array description: 기간·요일별 전체 운영시간. 배열 순서와 관계없이 isCurrent가 true인 항목이 현재 적용되는 운영시간 @@ -55,7 +55,7 @@ example: address: 서울특별시 광진구 능동로 120 latitude: 37.541823 longitude: 127.0779007 - imageUrl: https://placehold.co/1200x800/png?text=Konkuk+University + imageUrl: https://placehold.co/1200x800/png?text=Student+Center operatingHours: - period: SEMESTER dayGroup: WEEKDAY @@ -86,7 +86,7 @@ example: name: 학생회관 복사실 category: printer categoryKorName: 프린터 - imageUrl: https://placehold.co/600x400/png?text=Printer + imageUrl: https://placehold.co/1200x800/png?text=Student+Center locationType: INDOOR floor: 1F locationDetail: 학생회관 1층 @@ -121,7 +121,7 @@ example: name: 신한은행 category: bank_atm categoryKorName: 은행·ATM - imageUrl: https://placehold.co/600x400/png?text=ATM + imageUrl: https://placehold.co/1200x800/png?text=Student+Center locationType: INDOOR floor: 1F locationDetail: 학생회관 1층 diff --git a/components/schemas/campus-map/BuildingListResponse.yaml b/components/schemas/campus-map/BuildingListResponse.yaml index 1832ed6..d01ca39 100644 --- a/components/schemas/campus-map/BuildingListResponse.yaml +++ b/components/schemas/campus-map/BuildingListResponse.yaml @@ -7,7 +7,7 @@ properties: type: array description: 캠퍼스에 등록된 건물 목록 items: - $ref: ./BuildingSummary.yaml + $ref: ./BuildingOverview.yaml example: buildings: - id: 1 @@ -15,28 +15,34 @@ example: address: 서울특별시 광진구 능동로 120 latitude: 37.5444801 longitude: 127.0748518 + displayOrder: 1 - id: 2 name: 경영관 address: 서울특별시 광진구 능동로 120 latitude: 37.5443474 longitude: 127.0761119 + displayOrder: 1 - id: 3 name: 법학관 address: 서울특별시 광진구 능동로 120 latitude: 37.5417036 longitude: 127.0750767 + displayOrder: 1 - id: 4 name: 학생회관 address: 서울특별시 광진구 능동로 120 latitude: 37.541823 longitude: 127.0779007 + displayOrder: 2 - id: 10 name: 상허기념도서관 address: 서울특별시 광진구 능동로 120 latitude: 37.5420474 longitude: 127.0738384 + displayOrder: 2 - id: 20 name: 과학관 address: 서울특별시 광진구 능동로 120 latitude: 37.541467 longitude: 127.0805824 + displayOrder: 3 \ No newline at end of file diff --git a/components/schemas/campus-map/BuildingOverview.yaml b/components/schemas/campus-map/BuildingOverview.yaml new file mode 100644 index 0000000..e5e1f67 --- /dev/null +++ b/components/schemas/campus-map/BuildingOverview.yaml @@ -0,0 +1,40 @@ +title: BuildingOverview +type: object +description: 캠퍼스맵 전체 건물 목록에 표시되는 건물 정보 +required: + - id + - name + - address + - latitude + - longitude + - displayOrder +properties: + id: + type: integer + format: int64 + description: 건물 ID + example: 35 + name: + type: string + description: 건물명 + example: 학생회관 + address: + type: string + description: 건물 주소 + example: 서울특별시 광진구 능동로 120 + latitude: + type: number + format: double + description: 건물 위도 + example: 37.541875 + longitude: + type: number + format: double + description: 건물 경도 + example: 127.077966 + displayOrder: + type: integer + format: int32 + nullable: true + description: 건물 노출 우선순위. 값이 없으면 우선순위가 지정된 건물 다음에 노출됩니다. + example: 1 \ No newline at end of file diff --git a/components/schemas/campus-map/CampusMapSearchResponse.yaml b/components/schemas/campus-map/CampusMapSearchResponse.yaml new file mode 100644 index 0000000..5046bef --- /dev/null +++ b/components/schemas/campus-map/CampusMapSearchResponse.yaml @@ -0,0 +1,65 @@ +type: object +description: 캠퍼스맵 건물 및 시설 통합 검색 응답의 data +required: + - buildings + - campusPlaces +properties: + buildings: + type: array + description: 건물명, 주소 또는 등록된 검색 키워드와 일치하는 건물 목록 + items: + $ref: ./BuildingSummary.yaml + campusPlaces: + type: array + description: 시설명 또는 시설 카테고리와 일치하는 시설 목록 + items: + $ref: ./CampusPlaceItem.yaml +example: + buildings: + - id: 3 + name: 법학관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5417036 + longitude: 127.0750767 + campusPlaces: + - id: 301 + name: 법학관 인쇄소 + category: printer + categoryKorName: 프린터 + imageUrl: https://placehold.co/1200x800/png?text=Law+Building + locationType: INDOOR + floor: B1 + locationDetail: 법학관 지하 1층 + quantity: 1 + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '22:00' + isCurrent: true + - period: SEMESTER + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false + externalUrl: null + building: + id: 3 + name: 법학관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.5417036 + longitude: 127.0750767 \ No newline at end of file diff --git a/components/schemas/campus-map/CampusPlaceDetail.yaml b/components/schemas/campus-map/CampusPlaceDetail.yaml index c5459c5..ef45ac8 100644 --- a/components/schemas/campus-map/CampusPlaceDetail.yaml +++ b/components/schemas/campus-map/CampusPlaceDetail.yaml @@ -32,7 +32,7 @@ properties: - `smoking_booth`: 흡연부스 - `convenience_store`: 편의점 - `lounge`: 휴게실 - - `kcube`: KCUBE + - `kcube`: K-Cube - `bank_atm`: 은행·ATM - `post_office`: 우체국 enum: @@ -48,14 +48,14 @@ properties: example: printer categoryKorName: type: string - description: 클라이언트 화면에 표시할 카테고리 한글명 + description: 클라이언트 화면에 표시할 카테고리명 example: 프린터 imageUrl: type: string format: uri nullable: true - description: 시설 이미지 URL. 등록된 이미지가 없으면 null - example: https://placehold.co/600x400/png?text=Printer + description: 시설이 속한 건물의 이미지 URL. 건물 이미지가 없으면 null + example: https://placehold.co/1200x800/png?text=Law+Building locationType: type: string description: |- @@ -98,7 +98,7 @@ example: name: 법학관 인쇄소 category: printer categoryKorName: 프린터 - imageUrl: https://placehold.co/600x400/png?text=Printer + imageUrl: https://placehold.co/1200x800/png?text=Law+Building locationType: INDOOR floor: B1 locationDetail: 법학관 지하 1층 @@ -128,4 +128,4 @@ example: opensAt: null closesAt: null isCurrent: false - externalUrl: null + externalUrl: null \ No newline at end of file diff --git a/components/schemas/campus-map/CampusPlaceItem.yaml b/components/schemas/campus-map/CampusPlaceItem.yaml index a09602c..4892736 100644 --- a/components/schemas/campus-map/CampusPlaceItem.yaml +++ b/components/schemas/campus-map/CampusPlaceItem.yaml @@ -33,7 +33,7 @@ properties: - `smoking_booth`: 흡연부스 - `convenience_store`: 편의점 - `lounge`: 휴게실 - - `kcube`: KCUBE + - `kcube`: K-Cube enum: - cafe - restaurant @@ -45,14 +45,14 @@ properties: example: printer categoryKorName: type: string - description: 카테고리 한글명 + description: 카테고리 표시명 example: 프린터 imageUrl: type: string format: uri nullable: true - description: 시설 이미지 URL. 등록된 이미지가 없으면 null - example: https://placehold.co/600x400/png?text=Printer + description: 시설이 속한 건물의 이미지 URL. 건물 이미지가 없으면 null + example: https://placehold.co/1200x800/png?text=Law+Building locationType: type: string description: |- @@ -97,7 +97,7 @@ example: name: 법학관 인쇄소 category: printer categoryKorName: 프린터 - imageUrl: https://placehold.co/600x400/png?text=Printer + imageUrl: https://placehold.co/1200x800/png?text=Law+Building locationType: INDOOR floor: B1 locationDetail: 법학관 지하 1층 @@ -133,4 +133,4 @@ example: name: 법학관 address: 서울특별시 광진구 능동로 120 latitude: 37.5417036 - longitude: 127.0750767 + longitude: 127.0750767 \ No newline at end of file diff --git a/components/schemas/campus-map/CampusPlaceListResponse.yaml b/components/schemas/campus-map/CampusPlaceListResponse.yaml index f216a74..b167b65 100644 --- a/components/schemas/campus-map/CampusPlaceListResponse.yaml +++ b/components/schemas/campus-map/CampusPlaceListResponse.yaml @@ -14,7 +14,7 @@ example: name: 법학관 인쇄소 category: printer categoryKorName: 프린터 - imageUrl: https://placehold.co/600x400/png?text=Printer + imageUrl: https://placehold.co/1200x800/png?text=Law+Building locationType: INDOOR floor: B1 locationDetail: 법학관 지하 1층 @@ -55,7 +55,7 @@ example: name: 경영관 흡연부스 category: smoking_booth categoryKorName: 흡연부스 - imageUrl: https://placehold.co/600x400/png?text=Smoking+Booth + imageUrl: https://placehold.co/1200x800/png?text=Business+Building locationType: OUTDOOR floor: OUTDOOR locationDetail: 경영관 CU 앞 diff --git a/components/schemas/campus-map/CategoryDto.yaml b/components/schemas/campus-map/CategoryDto.yaml index 2e06acd..7227b68 100644 --- a/components/schemas/campus-map/CategoryDto.yaml +++ b/components/schemas/campus-map/CategoryDto.yaml @@ -15,7 +15,7 @@ properties: - `smoking_booth`: 흡연부스 - `convenience_store`: 편의점 - `lounge`: 휴게실 - - `kcube`: KCUBE + - `kcube`: K-Cube enum: - cafe - restaurant diff --git a/components/schemas/campus-map/CategoryListResponse.yaml b/components/schemas/campus-map/CategoryListResponse.yaml index a5e08f4..720b323 100644 --- a/components/schemas/campus-map/CategoryListResponse.yaml +++ b/components/schemas/campus-map/CategoryListResponse.yaml @@ -29,5 +29,5 @@ example: korName: 휴게실 displayOrder: 6 - name: kcube - korName: KCUBE - displayOrder: 7 + korName: K-Cube + displayOrder: 7 \ No newline at end of file diff --git a/openapi.yaml b/openapi.yaml index ad0f377..5e850d0 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2131,7 +2131,7 @@ paths: korName: 휴게실 displayOrder: 6 - name: kcube - korName: KCUBE + korName: K-Cube displayOrder: 7 operationId: getCampusMapCategories x-stoplight: @@ -2170,31 +2170,37 @@ paths: address: 서울특별시 광진구 능동로 120 latitude: 37.5444801 longitude: 127.0748518 + displayOrder: 1 - id: 2 name: 경영관 address: 서울특별시 광진구 능동로 120 latitude: 37.5443474 longitude: 127.0761119 + displayOrder: 1 - id: 3 name: 법학관 address: 서울특별시 광진구 능동로 120 latitude: 37.5417036 longitude: 127.0750767 + displayOrder: 1 - id: 4 name: 학생회관 address: 서울특별시 광진구 능동로 120 latitude: 37.541823 longitude: 127.0779007 + displayOrder: 2 - id: 10 name: 상허기념도서관 address: 서울특별시 광진구 능동로 120 latitude: 37.5420474 longitude: 127.0738384 + displayOrder: 2 - id: 20 name: 과학관 address: 서울특별시 광진구 능동로 120 latitude: 37.541467 longitude: 127.0805824 + displayOrder: 3 operationId: getCampusMapBuildings x-stoplight: id: 9ml6ohwg6sodd @@ -2203,12 +2209,21 @@ paths: 건물 상세 정보와 건물 내부 시설 정보는 포함하지 않습니다. /api/v2/maps/buildings/search: get: - summary: 캠퍼스맵 건물 키워드 검색 + summary: 캠퍼스맵 건물 및 시설 키워드 검색 tags: - Draft + parameters: + - schema: + type: string + example: 학생회관 + minLength: 1 + in: query + name: keyword + required: true + description: 건물명, 주소, 건물 검색 키워드, 시설명 또는 시설 카테고리 검색어 responses: '200': - description: 캠퍼스맵 건물 키워드 검색 성공 + description: 캠퍼스맵 건물 및 시설 키워드 검색 성공 content: application/json: schema: @@ -2219,12 +2234,12 @@ paths: - data properties: data: - $ref: ./components/schemas/campus-map/BuildingListResponse.yaml + $ref: ./components/schemas/campus-map/CampusMapSearchResponse.yaml examples: Success: value: code: 200 - message: 캠퍼스 건물 검색에 성공하였습니다 + message: 캠퍼스맵 검색에 성공하였습니다 data: buildings: - id: 4 @@ -2232,12 +2247,55 @@ paths: address: 서울특별시 광진구 능동로 120 latitude: 37.541823 longitude: 127.0779007 + campusPlaces: + - id: 401 + name: 학생회관 식당 + category: restaurant + categoryKorName: 식당 + imageUrl: https://placehold.co/1200x800/png?text=Student+Center + locationType: INDOOR + floor: 1F + locationDetail: 학생회관 1층 + quantity: null + operatingHours: + - period: SEMESTER + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '08:00' + closesAt: '20:00' + isCurrent: true + - period: SEMESTER + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false + - period: VACATION + dayGroup: WEEKDAY + status: SCHEDULED + opensAt: '09:00' + closesAt: '18:00' + isCurrent: false + - period: VACATION + dayGroup: WEEKEND + status: UNKNOWN + opensAt: null + closesAt: null + isCurrent: false + externalUrl: null + building: + id: 4 + name: 학생회관 + address: 서울특별시 광진구 능동로 120 + latitude: 37.541823 + longitude: 127.0779007 EmptyResult: value: code: 200 - message: 캠퍼스 건물 검색에 성공하였습니다 + message: 캠퍼스맵 검색에 성공하였습니다 data: buildings: [] + campusPlaces: [] '400': description: 검색어 누락 또는 잘못된 검색어 content: @@ -2255,21 +2313,13 @@ paths: isSuccess: false resultCode: 400 resultMsg: 파라미터 값 중 잘못된 값이 있습니다. - operationId: searchCampusMapBuildings + operationId: searchCampusMap x-stoplight: id: 4t1enp1xlx2z9 description: |- - 건물명, 주소 또는 건물에 등록된 검색 키워드를 기준으로 건물을 검색합니다. - 시설명은 검색 대상에 포함하지 않습니다. - parameters: - - schema: - type: string - example: 학관 - minLength: 1 - in: query - name: keyword - required: true - description: 건물명 또는 건물에 등록된 검색 키워드 + 입력한 키워드로 건물과 캠퍼스 시설을 함께 검색합니다. + 건물은 건물명, 주소 또는 등록된 건물 검색 키워드를 대상으로 검색합니다. + 시설은 시설명, 카테고리 코드 또는 카테고리 한글명을 대상으로 검색합니다. /api/v2/maps/campus-places: get: summary: 캠퍼스맵 카테고리 기반 시설 목록 조회 @@ -2295,7 +2345,7 @@ paths: - `smoking_booth`: 흡연부스 - `convenience_store`: 편의점 - `lounge`: 휴게실 - - `kcube`: KCUBE + - `kcube`: K-Cube enum: - cafe - restaurant @@ -2332,7 +2382,7 @@ paths: name: 법학관 인쇄소 category: printer categoryKorName: 프린터 - imageUrl: 'https://placehold.co/600x400/png?text=Printer' + imageUrl: 'https://placehold.co/1200x800/png?text=Law+Building' locationType: INDOOR floor: B1 locationDetail: 법학관 지하 1층 @@ -2373,7 +2423,7 @@ paths: name: 경영관 흡연부스 category: smoking_booth categoryKorName: 흡연부스 - imageUrl: 'https://placehold.co/600x400/png?text=Smoking+Booth' + imageUrl: 'https://placehold.co/1200x800/png?text=Business+Building' locationType: OUTDOOR floor: OUTDOOR locationDetail: 경영관 CU 앞 @@ -2475,7 +2525,7 @@ paths: address: 서울특별시 광진구 능동로 120 latitude: 37.541823 longitude: 127.0779007 - imageUrl: https://placehold.co/1200x800/png?text=Konkuk+University + imageUrl: https://placehold.co/1200x800/png?text=Student+Center operatingHours: - period: SEMESTER dayGroup: WEEKDAY @@ -2506,7 +2556,7 @@ paths: name: 학생회관 복사실 category: printer categoryKorName: 프린터 - imageUrl: https://placehold.co/600x400/png?text=Printer + imageUrl: https://placehold.co/1200x800/png?text=Student+Center locationType: INDOOR floor: 1F locationDetail: 학생회관 1층 @@ -2541,7 +2591,7 @@ paths: name: 신한은행 category: bank_atm categoryKorName: 은행·ATM - imageUrl: https://placehold.co/600x400/png?text=ATM + imageUrl: https://placehold.co/1200x800/png?text=Student+Center locationType: INDOOR floor: 1F locationDetail: 학생회관 1층 From c3c7aa668d659fc5afd3243fe74d3f3845c11cb7 Mon Sep 17 00:00:00 2001 From: "kuring.korea@gmail.com" Date: Tue, 25 Aug 2026 14:11:08 +0900 Subject: [PATCH 4/4] =?UTF-8?q?Docs:=20=EC=BA=A0=ED=8D=BC=EC=8A=A4?= =?UTF-8?q?=EB=A7=B5=20=EA=B2=80=EC=83=89=20=EA=B1=B4=EB=AC=BC=20=EC=9D=B4?= =?UTF-8?q?=EB=AF=B8=EC=A7=80=20=EC=9D=91=EB=8B=B5=20=EB=B0=98=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Committed by rlagkswn00 on behalf of kuring.korea@gmail.com --- .../schemas/campus-map/BuildingSummary.yaml | 8 ++++ .../campus-map/CampusMapSearchResponse.yaml | 40 ++++++++++--------- .../schemas/campus-map/CampusPlaceItem.yaml | 3 +- .../campus-map/CampusPlaceListResponse.yaml | 2 + openapi.yaml | 6 ++- 5 files changed, 38 insertions(+), 21 deletions(-) diff --git a/components/schemas/campus-map/BuildingSummary.yaml b/components/schemas/campus-map/BuildingSummary.yaml index a5d2456..562e7ab 100644 --- a/components/schemas/campus-map/BuildingSummary.yaml +++ b/components/schemas/campus-map/BuildingSummary.yaml @@ -6,6 +6,7 @@ required: - address - latitude - longitude + - imageUrl properties: id: type: integer @@ -30,9 +31,16 @@ properties: format: double description: 건물 경도 example: 127.0779007 + imageUrl: + type: string + format: uri + nullable: true + description: 건물 이미지 URL. 등록된 이미지가 없으면 null + example: https://cdn.example.com/campus-map/student-center.jpg example: id: 4 name: 학생회관 address: 서울특별시 광진구 능동로 120 latitude: 37.541823 longitude: 127.0779007 + imageUrl: https://cdn.example.com/campus-map/student-center.jpg \ No newline at end of file diff --git a/components/schemas/campus-map/CampusMapSearchResponse.yaml b/components/schemas/campus-map/CampusMapSearchResponse.yaml index 5046bef..0d333ed 100644 --- a/components/schemas/campus-map/CampusMapSearchResponse.yaml +++ b/components/schemas/campus-map/CampusMapSearchResponse.yaml @@ -6,37 +6,38 @@ required: properties: buildings: type: array - description: 건물명, 주소 또는 등록된 검색 키워드와 일치하는 건물 목록 + description: 검색어와 일치하는 건물 목록 items: $ref: ./BuildingSummary.yaml campusPlaces: type: array - description: 시설명 또는 시설 카테고리와 일치하는 시설 목록 + description: 검색어와 일치하는 캠퍼스 시설 목록 items: $ref: ./CampusPlaceItem.yaml example: buildings: - - id: 3 - name: 법학관 + - id: 4 + name: 학생회관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5417036 - longitude: 127.0750767 + latitude: 37.541823 + longitude: 127.0779007 + imageUrl: https://cdn.example.com/campus-map/student-center.jpg campusPlaces: - - id: 301 - name: 법학관 인쇄소 - category: printer - categoryKorName: 프린터 - imageUrl: https://placehold.co/1200x800/png?text=Law+Building + - id: 401 + name: 학생회관 식당 + category: restaurant + categoryKorName: 식당 + imageUrl: https://cdn.example.com/campus-map/student-center.jpg locationType: INDOOR - floor: B1 - locationDetail: 법학관 지하 1층 - quantity: 1 + floor: 1F + locationDetail: 학생회관 1층 + quantity: null operatingHours: - period: SEMESTER dayGroup: WEEKDAY status: SCHEDULED opensAt: '08:00' - closesAt: '22:00' + closesAt: '20:00' isCurrent: true - period: SEMESTER dayGroup: WEEKEND @@ -58,8 +59,9 @@ example: isCurrent: false externalUrl: null building: - id: 3 - name: 법학관 + id: 4 + name: 학생회관 address: 서울특별시 광진구 능동로 120 - latitude: 37.5417036 - longitude: 127.0750767 \ No newline at end of file + latitude: 37.541823 + longitude: 127.0779007 + imageUrl: https://cdn.example.com/campus-map/student-center.jpg \ No newline at end of file diff --git a/components/schemas/campus-map/CampusPlaceItem.yaml b/components/schemas/campus-map/CampusPlaceItem.yaml index 4892736..6e8fdfe 100644 --- a/components/schemas/campus-map/CampusPlaceItem.yaml +++ b/components/schemas/campus-map/CampusPlaceItem.yaml @@ -133,4 +133,5 @@ example: name: 법학관 address: 서울특별시 광진구 능동로 120 latitude: 37.5417036 - longitude: 127.0750767 \ No newline at end of file + longitude: 127.0750767 + imageUrl: https://cdn.example.com/campus-map/law-building.jpg \ No newline at end of file diff --git a/components/schemas/campus-map/CampusPlaceListResponse.yaml b/components/schemas/campus-map/CampusPlaceListResponse.yaml index b167b65..3fe3dc2 100644 --- a/components/schemas/campus-map/CampusPlaceListResponse.yaml +++ b/components/schemas/campus-map/CampusPlaceListResponse.yaml @@ -51,6 +51,7 @@ example: address: 서울특별시 광진구 능동로 120 latitude: 37.5417036 longitude: 127.0750767 + imageUrl: https://cdn.example.com/campus-map/law-building.jpg - id: 205 name: 경영관 흡연부스 category: smoking_booth @@ -92,3 +93,4 @@ example: address: 서울특별시 광진구 능동로 120 latitude: 37.5443474 longitude: 127.0761119 + imageUrl: https://cdn.example.com/campus-map/business-building.jpg diff --git a/openapi.yaml b/openapi.yaml index 5e850d0..42ed5cd 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2247,12 +2247,13 @@ paths: address: 서울특별시 광진구 능동로 120 latitude: 37.541823 longitude: 127.0779007 + imageUrl: https://cdn.example.com/campus-map/student-center.jpg campusPlaces: - id: 401 name: 학생회관 식당 category: restaurant categoryKorName: 식당 - imageUrl: https://placehold.co/1200x800/png?text=Student+Center + imageUrl: https://cdn.example.com/campus-map/student-center.jpg locationType: INDOOR floor: 1F locationDetail: 학생회관 1층 @@ -2289,6 +2290,7 @@ paths: address: 서울특별시 광진구 능동로 120 latitude: 37.541823 longitude: 127.0779007 + imageUrl: https://cdn.example.com/campus-map/student-center.jpg EmptyResult: value: code: 200 @@ -2419,6 +2421,7 @@ paths: address: 서울특별시 광진구 능동로 120 latitude: 37.5417036 longitude: 127.0750767 + imageUrl: https://placehold.co/1200x800/png?text=Law+Building - id: 205 name: 경영관 흡연부스 category: smoking_booth @@ -2460,6 +2463,7 @@ paths: address: 서울특별시 광진구 능동로 120 latitude: 37.5443474 longitude: 127.0761119 + imageUrl: https://placehold.co/1200x800/png?text=Business+Building EmptyResult: value: code: 200