From 3b314146c8a8ad74d2df8fa8e7f8a0df9123bcce Mon Sep 17 00:00:00 2001 From: Seo Jean Kang <119040660+c0smosaur@users.noreply.github.com> Date: Mon, 17 Jun 2024 12:23:20 +0900 Subject: [PATCH] =?UTF-8?q?[DOC]=20#141=20Swagger=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../club/club/controller/ClubController.java | 2 + .../club/controller/ClubMemberController.java | 2 + .../controller/ClubMeetingController.java | 2 + .../controller/ClubCommentController.java | 2 + .../controller/ClubNoticeController.java | 2 + .../linkup/common/config/SecurityConfig.java | 7 +- .../linkup/common/config/SwaggerConfig.java | 72 +++++++++++++++++++ .../common/controller/CategoryController.java | 2 + .../member/controller/MemberController.java | 2 + .../office/controller/OfficeController.java | 2 + ...ompanyMembershipReservationController.java | 3 +- ...vidualMembershipReservationController.java | 2 + .../controller/ReservationController.java | 2 + 13 files changed, 100 insertions(+), 2 deletions(-) create mode 100644 src/main/java/com/core/linkup/common/config/SwaggerConfig.java diff --git a/src/main/java/com/core/linkup/club/club/controller/ClubController.java b/src/main/java/com/core/linkup/club/club/controller/ClubController.java index 940b548..db1bceb 100644 --- a/src/main/java/com/core/linkup/club/club/controller/ClubController.java +++ b/src/main/java/com/core/linkup/club/club/controller/ClubController.java @@ -6,6 +6,7 @@ import com.core.linkup.common.response.BaseResponse; import com.core.linkup.common.response.BaseResponseStatus; import com.core.linkup.security.MemberDetails; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.data.domain.Page; import org.springframework.data.domain.Pageable; @@ -17,6 +18,7 @@ @RestController @RequiredArgsConstructor @RequestMapping("/api/v1/club") +@Tag(name = "Club", description = "소모임 관련 API") public class ClubController { private final ClubService clubService; diff --git a/src/main/java/com/core/linkup/club/club/controller/ClubMemberController.java b/src/main/java/com/core/linkup/club/club/controller/ClubMemberController.java index 2651f42..c741dd4 100644 --- a/src/main/java/com/core/linkup/club/club/controller/ClubMemberController.java +++ b/src/main/java/com/core/linkup/club/club/controller/ClubMemberController.java @@ -9,6 +9,7 @@ import com.core.linkup.common.response.BaseResponse; import com.core.linkup.common.response.BaseResponseStatus; import com.core.linkup.security.MemberDetails; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.data.domain.Page; import org.springframework.data.domain.PageRequest; @@ -23,6 +24,7 @@ @RestController @RequestMapping("/api/v1/club") @RequiredArgsConstructor +@Tag(name = "Club - Member", description = "소모임 인원 관리 관련 API") public class ClubMemberController { private final ClubMemberService clubMemberService; diff --git a/src/main/java/com/core/linkup/club/clubmeeting/controller/ClubMeetingController.java b/src/main/java/com/core/linkup/club/clubmeeting/controller/ClubMeetingController.java index 9174fc1..9e3f558 100644 --- a/src/main/java/com/core/linkup/club/clubmeeting/controller/ClubMeetingController.java +++ b/src/main/java/com/core/linkup/club/clubmeeting/controller/ClubMeetingController.java @@ -6,6 +6,7 @@ import com.core.linkup.common.response.BaseResponse; import com.core.linkup.common.response.BaseResponseStatus; import com.core.linkup.security.MemberDetails; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.security.core.annotation.AuthenticationPrincipal; import org.springframework.web.bind.annotation.*; @@ -15,6 +16,7 @@ @RestController @RequiredArgsConstructor @RequestMapping("/api/v1/club") +@Tag(name = "Club", description = "소모임 정모 관련 API") public class ClubMeetingController { private final ClubMeetingService clubMeetingService; diff --git a/src/main/java/com/core/linkup/club/clubnotice/controller/ClubCommentController.java b/src/main/java/com/core/linkup/club/clubnotice/controller/ClubCommentController.java index 1aa8b8a..62be917 100644 --- a/src/main/java/com/core/linkup/club/clubnotice/controller/ClubCommentController.java +++ b/src/main/java/com/core/linkup/club/clubnotice/controller/ClubCommentController.java @@ -6,6 +6,7 @@ import com.core.linkup.common.response.BaseResponse; import com.core.linkup.common.response.BaseResponseStatus; import com.core.linkup.security.MemberDetails; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.security.core.annotation.AuthenticationPrincipal; import org.springframework.web.bind.annotation.*; @@ -15,6 +16,7 @@ @RestController @RequiredArgsConstructor @RequestMapping("/api/v1/club") +@Tag(name = "Club - Comment", description = "소모임 댓글 관련 API") public class ClubCommentController { private final ClubCommentService clubCommentService; diff --git a/src/main/java/com/core/linkup/club/clubnotice/controller/ClubNoticeController.java b/src/main/java/com/core/linkup/club/clubnotice/controller/ClubNoticeController.java index 6b2c938..83095ff 100644 --- a/src/main/java/com/core/linkup/club/clubnotice/controller/ClubNoticeController.java +++ b/src/main/java/com/core/linkup/club/clubnotice/controller/ClubNoticeController.java @@ -6,6 +6,7 @@ import com.core.linkup.common.response.BaseResponse; import com.core.linkup.common.response.BaseResponseStatus; import com.core.linkup.security.MemberDetails; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.data.domain.Page; import org.springframework.data.domain.PageRequest; @@ -16,6 +17,7 @@ @RestController @RequiredArgsConstructor @RequestMapping("/api/v1/club") +@Tag(name = "Club - Notice", description = "소모임 게시글/공지사항 관련 API") public class ClubNoticeController { private final ClubNoticeService clubNoticeService; diff --git a/src/main/java/com/core/linkup/common/config/SecurityConfig.java b/src/main/java/com/core/linkup/common/config/SecurityConfig.java index 11bd077..64438c0 100644 --- a/src/main/java/com/core/linkup/common/config/SecurityConfig.java +++ b/src/main/java/com/core/linkup/common/config/SecurityConfig.java @@ -56,7 +56,12 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Excepti "/api/v1/category/*", //소모임 - 비로그인 범위 - "/api/v1/club/search").permitAll() + "/api/v1/club/search", + + // Swagger UI + "/v3/api-docs/**", + "/swagger-ui/**", + "/swagger-ui.html").permitAll() .anyRequest().authenticated()) .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) diff --git a/src/main/java/com/core/linkup/common/config/SwaggerConfig.java b/src/main/java/com/core/linkup/common/config/SwaggerConfig.java new file mode 100644 index 0000000..8625489 --- /dev/null +++ b/src/main/java/com/core/linkup/common/config/SwaggerConfig.java @@ -0,0 +1,72 @@ +package com.core.linkup.common.config; + +import com.fasterxml.jackson.databind.ObjectMapper; +import io.swagger.v3.core.jackson.ModelResolver; +import io.swagger.v3.oas.models.Components; +import io.swagger.v3.oas.models.OpenAPI; +import io.swagger.v3.oas.models.Operation; +import io.swagger.v3.oas.models.PathItem; +import io.swagger.v3.oas.models.info.Info; +import io.swagger.v3.oas.models.media.StringSchema; +import io.swagger.v3.oas.models.parameters.Parameter; +import io.swagger.v3.oas.models.responses.ApiResponse; +import io.swagger.v3.oas.models.responses.ApiResponses; +import io.swagger.v3.oas.models.security.SecurityRequirement; +import io.swagger.v3.oas.models.security.SecurityScheme; +import io.swagger.v3.oas.models.servers.Server; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +import java.util.List; + +@Configuration +public class SwaggerConfig { + private static final String SECURITY_SCHEME_NAME = "Authorization"; + private static final String SECURITY_SCHEME_REFRESH_NAME = "refresh-token"; + + @Bean + public ModelResolver modelResolver(ObjectMapper objectMapper) { + return new ModelResolver(objectMapper); + } + + @Bean + public OpenAPI swaggerApi(){ + return new OpenAPI() + .components(new Components() + .addSecuritySchemes(SECURITY_SCHEME_NAME, new SecurityScheme() + .name(SECURITY_SCHEME_NAME) + .type(SecurityScheme.Type.HTTP) + .scheme("Bearer") + .bearerFormat("JWT")) + .addSecuritySchemes(SECURITY_SCHEME_REFRESH_NAME, new SecurityScheme() + .name(SECURITY_SCHEME_REFRESH_NAME) + .type(SecurityScheme.Type.HTTP) + .in(SecurityScheme.In.HEADER) + .scheme("Bearer") + .bearerFormat("JWT")) + ) + .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME)) + .info(new Info() + .title("패스트캠퍼스 기업연계 프로젝트-3조 LinkUp 백엔드") + .description("공유오피스 서비스 프로젝트")) + .servers(List.of( + new Server().url("https://api.linkup3mw.com"))) + .path("/api/v1/member/logout", new PathItem() + .get(new Operation() + .operationId("logout") + .description("Log out the current user") + .addTagsItem("Authentication") + .addParametersItem(new Parameter() + .in("header") + .name("Logout") + .description("Bearer token") + .required(true) + .schema(new StringSchema().format("string")) + .example("Bearer ")) + .responses(new ApiResponses() + .addApiResponse("200", new ApiResponse() + .description("Logout successful")) + .addApiResponse("401", new ApiResponse() + .description("Unauthorized"))))); + } +} diff --git a/src/main/java/com/core/linkup/common/controller/CategoryController.java b/src/main/java/com/core/linkup/common/controller/CategoryController.java index 1aa3ed7..9308c2f 100644 --- a/src/main/java/com/core/linkup/common/controller/CategoryController.java +++ b/src/main/java/com/core/linkup/common/controller/CategoryController.java @@ -5,6 +5,7 @@ import com.core.linkup.common.entity.enums.IndustryType; import com.core.linkup.common.entity.enums.OccupationType; import com.core.linkup.common.response.BaseResponse; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; @@ -19,6 +20,7 @@ @RestController @RequiredArgsConstructor @RequestMapping("/api/v1/category") +@Tag(name = "Category", description = "프론트 필터링에 필요한 카테고리 제공 API") public class CategoryController { @GetMapping("/city") diff --git a/src/main/java/com/core/linkup/member/controller/MemberController.java b/src/main/java/com/core/linkup/member/controller/MemberController.java index b6f222f..bc86204 100644 --- a/src/main/java/com/core/linkup/member/controller/MemberController.java +++ b/src/main/java/com/core/linkup/member/controller/MemberController.java @@ -9,6 +9,7 @@ import com.core.linkup.member.service.MemberService; import com.core.linkup.member.service.ValidationService; import com.core.linkup.security.MemberDetails; +import io.swagger.v3.oas.annotations.tags.Tag; import jakarta.servlet.http.HttpServletResponse; import jakarta.validation.Valid; import lombok.RequiredArgsConstructor; @@ -23,6 +24,7 @@ @RestController @RequiredArgsConstructor @RequestMapping("/api/v1/member") +@Tag(name = "Authentication", description = "인증/인가 관련 API") public class MemberController { private final MemberService memberService; diff --git a/src/main/java/com/core/linkup/office/controller/OfficeController.java b/src/main/java/com/core/linkup/office/controller/OfficeController.java index 7eb4d12..f2ee088 100644 --- a/src/main/java/com/core/linkup/office/controller/OfficeController.java +++ b/src/main/java/com/core/linkup/office/controller/OfficeController.java @@ -6,6 +6,7 @@ import com.core.linkup.office.response.OfficeResponse; import com.core.linkup.office.response.OfficeSearchResponse; import com.core.linkup.office.service.OfficeService; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.data.domain.Page; import org.springframework.data.domain.Pageable; @@ -16,6 +17,7 @@ @RestController @RequiredArgsConstructor @RequestMapping("/api/v1/office") +@Tag(name = "Search", description = "지점 탐색 관련 API") public class OfficeController { private final OfficeService officeService; diff --git a/src/main/java/com/core/linkup/reservation/reservation/controller/CompanyMembershipReservationController.java b/src/main/java/com/core/linkup/reservation/reservation/controller/CompanyMembershipReservationController.java index 0d905ef..efd0fd0 100644 --- a/src/main/java/com/core/linkup/reservation/reservation/controller/CompanyMembershipReservationController.java +++ b/src/main/java/com/core/linkup/reservation/reservation/controller/CompanyMembershipReservationController.java @@ -9,6 +9,7 @@ import com.core.linkup.reservation.reservation.response.ReservationResponse; import com.core.linkup.reservation.reservation.service.CompanyMembershipReservationService; import com.core.linkup.security.MemberDetails; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.security.core.annotation.AuthenticationPrincipal; @@ -19,7 +20,7 @@ @Slf4j @RestController @RequestMapping("/api/v1/reservation/company") -@RequiredArgsConstructor +@RequiredArgsConstructor@Tag(name = "Reservation - Company", description = "기업 멤버십 예약 관련 API") public class CompanyMembershipReservationController { private final CompanyMembershipReservationService companyMembershipReservationService; diff --git a/src/main/java/com/core/linkup/reservation/reservation/controller/IndividualMembershipReservationController.java b/src/main/java/com/core/linkup/reservation/reservation/controller/IndividualMembershipReservationController.java index 39ca4f2..98c32bb 100644 --- a/src/main/java/com/core/linkup/reservation/reservation/controller/IndividualMembershipReservationController.java +++ b/src/main/java/com/core/linkup/reservation/reservation/controller/IndividualMembershipReservationController.java @@ -7,6 +7,7 @@ import com.core.linkup.reservation.reservation.response.*; import com.core.linkup.reservation.reservation.service.IndividualMembershipReservationService; import com.core.linkup.security.MemberDetails; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.security.core.annotation.AuthenticationPrincipal; @@ -18,6 +19,7 @@ @RestController @RequiredArgsConstructor @RequestMapping("/api/v1/reservation/individual") +@Tag(name = "Reservation - Individual", description = "개인 멤버십 예약 관련 API") public class IndividualMembershipReservationController { private final IndividualMembershipReservationService individualMembershipReservationService; diff --git a/src/main/java/com/core/linkup/reservation/reservation/controller/ReservationController.java b/src/main/java/com/core/linkup/reservation/reservation/controller/ReservationController.java index 5ee32b7..deaad42 100644 --- a/src/main/java/com/core/linkup/reservation/reservation/controller/ReservationController.java +++ b/src/main/java/com/core/linkup/reservation/reservation/controller/ReservationController.java @@ -9,6 +9,7 @@ import com.core.linkup.reservation.reservation.service.ReservationService; import com.core.linkup.security.MemberDetails; import com.querydsl.core.Tuple; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.security.core.annotation.AuthenticationPrincipal; @@ -21,6 +22,7 @@ @RequiredArgsConstructor @RestController @RequestMapping("/api/v1/reservation") +@Tag(name = "Reservation", description = "예약 관련 API") public class ReservationController { private final MembershipReservationService membershipReservationService;