merge: docs/swagger to develop (#14)

Author: toychip

noweekend-core/core-api/build.gradle.kts

@@ -14,6 +14,10 @@ dependencies {
     implementation("org.springframework.boot:spring-boot-starter-security")
 
     testImplementation(project(":noweekend-tests:api-docs"))
+
+    implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0") {
+        exclude(group = "io.swagger.core.v3", module = "swagger-annotations")
+    }
 }
 
 tasks.named<BootJar>("bootJar") {

noweekend-core/core-api/src/main/kotlin/noweekend/core/api/config/SecurityConfig.kt

@@ -26,8 +26,8 @@ class SecurityConfig {
     fun permitDenyPathsOnDevelopment() = mapOf(
         "permit" to arrayOf(
             "/health",
-            "/api-docs/**",
             "/swagger-ui/**",
+            "/v3/api-docs/**",
         ),
         "deny" to arrayOf(),
     )
@@ -37,10 +37,11 @@ class SecurityConfig {
     fun permitDenyPathsOnProduction() = mapOf(
         "permit" to arrayOf(
             "/health",
+            "/swagger-ui/**",
+            "/v3/api-docs/**",
         ),
         "deny" to arrayOf(
-            "/api-docs/**",
-            "/swagger-ui/**",
+            "/example",
         ),
     )
 

noweekend-core/core-api/src/main/kotlin/noweekend/core/api/config/SwaggerConfig.kt

@@ -0,0 +1,43 @@
+package noweekend.core.api.config
+
+import io.swagger.v3.oas.models.Components
+import io.swagger.v3.oas.models.OpenAPI
+import io.swagger.v3.oas.models.info.Info
+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
+
+@Configuration
+class SwaggerConfig {
+    @Bean
+    fun noWeekendApi(): OpenAPI {
+        val info =
+            Info()
+                .title("noweekend Server API")
+                .description("noweekend Server API 명세서")
+                .version("v1.0.0")
+
+        val jwtSchemeName = "JWT TOKEN"
+
+        val securityRequirement = SecurityRequirement().addList(jwtSchemeName)
+
+        val components =
+            Components()
+                .addSecuritySchemes(
+                    jwtSchemeName,
+                    SecurityScheme()
+                        .name(jwtSchemeName)
+                        .type(SecurityScheme.Type.HTTP)
+                        .scheme("bearer")
+                        .bearerFormat("JWT"),
+                )
+
+        return OpenAPI()
+            .addServersItem(Server().url("https://noweekend.store"))
+            .info(info)
+            .addSecurityItem(securityRequirement)
+            .components(components)
+    }
+}

noweekend-core/core-api/src/main/kotlin/noweekend/core/api/controller/HealthController.kt

@@ -1,14 +1,17 @@
 package noweekend.core.api.controller
 
+import io.swagger.v3.oas.annotations.Hidden
 import org.springframework.http.HttpStatus
 import org.springframework.http.ResponseEntity
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.RestController
 
+@Hidden
 @RestController
 class HealthController {
     @GetMapping("/health")
     fun health(): ResponseEntity<*> {
-        return ResponseEntity.status(HttpStatus.OK).build<Any>()
+        return ResponseEntity.status(HttpStatus.OK)
+            .body("ok")
     }
 }

noweekend-core/core-api/src/main/kotlin/noweekend/core/api/controller/v1/AuthController.kt

@@ -1,5 +1,9 @@
 package noweekend.core.api.controller.v1
 
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.media.Content
+import io.swagger.v3.oas.annotations.media.Schema
+import io.swagger.v3.oas.annotations.tags.Tag
 import noweekend.client.google.GoogleClient
 import noweekend.client.google.GoogleUserInfoRequest
 import noweekend.core.api.controller.v1.request.LoginRequest
@@ -11,13 +15,46 @@ import org.springframework.web.bind.annotation.PostMapping
 import org.springframework.web.bind.annotation.RequestBody
 import org.springframework.web.bind.annotation.RequestMapping
 import org.springframework.web.bind.annotation.RestController
+import io.swagger.v3.oas.annotations.parameters.RequestBody as SwaggerRequestBody
+import io.swagger.v3.oas.annotations.responses.ApiResponse as SwaggerApiResponse
 
+@Tag(name = "인증", description = "소셜 로그인 및 인증 API")
 @RestController
 @RequestMapping("/api/v1/login")
 class AuthController(
     private val authService: AuthService,
     private val googleClient: GoogleClient,
 ) {
+
+    @Operation(
+        summary = "구글 로그인",
+        description = "구글 AccessToken을 이용한 회원 인증/가입 처리. 회원가입시 google accessToken과 name을 함께 보내주셔야하고, 로그인시에는 google accessToken만 보내주시면됩니다.",
+        requestBody = SwaggerRequestBody(
+            required = true,
+            content = [
+                Content(
+                    mediaType = "application/json",
+                    schema = Schema(implementation = LoginRequest::class),
+                ),
+            ],
+        ),
+        responses = [
+            SwaggerApiResponse(
+                responseCode = "200",
+                description = "로그인 성공",
+                content = [
+                    Content(
+                        mediaType = "application/json",
+                        schema = Schema(implementation = GoogleLoginResponse::class),
+                    ),
+                ],
+            ),
+            SwaggerApiResponse(
+                responseCode = "400",
+                description = "잘못된 요청",
+            ),
+        ],
+    )
     @PostMapping("/google")
     fun loginWithGoogle(
         @Validated @RequestBody req: LoginRequest,

noweekend-core/core-api/src/main/kotlin/noweekend/core/api/controller/v1/request/LoginRequest.kt

@@ -1,8 +1,14 @@
 package noweekend.core.api.controller.v1.request
 
+import io.swagger.v3.oas.annotations.media.Schema
 import jakarta.validation.constraints.NotBlank
 
+@Schema(description = "구글 로그인 요청 DTO")
 data class LoginRequest(
-    @field:NotBlank(message = "accessToken은 필수입니다.") val accessToken: String,
+    @field:NotBlank(message = "accessToken은 필수입니다.")
+    @field:Schema(description = "구글 OAuth AccessToken", example = "ya29.a0Af...")
+    val accessToken: String,
+
+    @field:Schema(description = "사용자 이름. 회원가입시 필수, 로그인시 null로 보내시면됩니다.", example = "홍길동")
     val name: String?,
 )

noweekend-core/core-api/src/main/kotlin/noweekend/core/api/controller/v1/response/GoogleLoginResponse.kt

@@ -1,7 +1,13 @@
 package noweekend.core.api.controller.v1.response
 
+import io.swagger.v3.oas.annotations.media.Schema
+
+@Schema(description = "구글 로그인 응답 DTO")
 data class GoogleLoginResponse(
+    @field:Schema(description = "구글 이메일", example = "[email protected]")
     val email: String,
+    @field:Schema(description = "이미 가입된 회원 여부")
     val exists: Boolean,
+    @field:Schema(description = "발급된 액세스 토큰", example = "eyJhbGciOiJIUzI1NiIsInR5cCI6...")
     val accessToken: String,
 )