docs: Add Auth Controller Docs (#116)

* feat(109): Update Submodule * docs(109): Add Auth Controller Docs 인증용 Resource 에 접근하는 경우 사용되는 api 문서 정리 * docs(109): Add DTO document used in authentication process * docs(109): Add missing documents
U-is-Ni-in-Korea · Aug 25, 2023 · e810a38 · e810a38
1 parent 8da8b1f
commit e810a38
Show file tree

Hide file tree

Showing 5 changed files with 97 additions and 6 deletions.
diff --git a/src/main/java/com/universe/uni/controller/AuthController.java b/src/main/java/com/universe/uni/controller/AuthController.java
@@ -36,16 +36,19 @@ public AuthTokenDto authByGoogle(@RequestBody AuthRequestDto request) {
 	}
 
 	@PostMapping("apple")
+    @Override
 	public AuthTokenDto authByApple(@RequestBody AuthRequestDto request) {
 		return authService.authWithAppleUser(request.code());
 	}
 
 	@GetMapping("kakao/callback")
+    @Override
 	public AuthRequestDto redirectKakaoAuth(@RequestParam(name = "code") String authenticationCode) {
 		return new AuthRequestDto(authenticationCode);
 	}
 
 	@GetMapping("google/callback")
+    @Override
 	public AuthRequestDto redirectGoogleAuth(@RequestParam(name = "code") String authenticationCode) {
 		return new AuthRequestDto(authenticationCode);
 	}

diff --git a/src/main/java/com/universe/uni/controller/docs/AuthControllerContract.java b/src/main/java/com/universe/uni/controller/docs/AuthControllerContract.java
@@ -2,10 +2,13 @@
 
 import com.universe.uni.dto.AuthTokenDto;
 import com.universe.uni.dto.request.AuthRequestDto;
+import com.universe.uni.exception.dto.ErrorResponse;
 
 import org.springframework.http.MediaType;
+import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestParam;
 
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
@@ -33,10 +36,10 @@ public interface AuthControllerContract {
             ),
             @ApiResponse(
                     responseCode = "500",
-                    description = "사용자 인증의 실패한 경우 입니다.",
+                    description = "UE500: 사용자 인증에 실패한 경우 입니다.",
                     content = @Content(
                             mediaType = MediaType.APPLICATION_JSON_VALUE,
-                            schema = @Schema(example = "{ \"code\": \"UE500\"}")
+                            schema = @Schema(implementation = ErrorResponse.class)
                     )
             )
     })
@@ -64,10 +67,10 @@ AuthTokenDto authByKakao(
             ),
             @ApiResponse(
                     responseCode = "500",
-                    description = "사용자 인증의 실패한 경우 입니다.",
+                    description = "UE500: 사용자 인증에 실패한 경우 입니다.",
                     content = @Content(
                             mediaType = MediaType.APPLICATION_JSON_VALUE,
-                            schema = @Schema(example = "{ \"code\": \"UE500\"}")
+                            schema = @Schema(implementation = ErrorResponse.class)
                     )
             )
     })
@@ -79,4 +82,75 @@ AuthTokenDto authByGoogle(
             )
             @RequestBody AuthRequestDto request
     );
+
+    @Operation(
+            summary = "Apple 인증",
+            description = "Apple 인증을 통해 유저 인증 토큰을 생성합니다."
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "성공",
+                    content = @Content(
+                            mediaType = MediaType.APPLICATION_JSON_VALUE,
+                            schema = @Schema(implementation = AuthTokenDto.class)
+                    )
+            ),
+            @ApiResponse(
+                    responseCode = "500",
+                    description = "UE500: 사용자 인증에 실패한 경우 입니다",
+                    content = @Content(
+                            mediaType = MediaType.APPLICATION_JSON_VALUE,
+                            schema = @Schema(implementation = ErrorResponse.class)
+                    )
+            )
+
+    })
+    @PostMapping("apple")
+    AuthTokenDto authByApple(
+            @Parameter(
+                    description = "Apple 에서 받은 identity Token",
+                    content = @Content(
+                            mediaType = MediaType.APPLICATION_JSON_VALUE,
+                            schema = @Schema(implementation = AuthRequestDto.class)
+                    )
+            )
+            @RequestBody AuthRequestDto request
+    );
+
+    @Operation(
+            summary = "카카오 인증 Redirect Link",
+            description = "카카오 웹 페이지 로그인을 통해 로그인한 코드를 받을 경우 사용합니다. 일반적으로 사용되지 않는 api",
+            hidden = true
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "인증 후 인증 코드를 담아서 보냅니다",
+                    content = @Content(
+                            mediaType = MediaType.APPLICATION_JSON_VALUE,
+                            schema = @Schema(implementation = AuthRequestDto.class)
+                    )
+            )
+    })
+    @GetMapping("kakao/callback")
+    AuthRequestDto redirectKakaoAuth(@RequestParam(name = "code") String authenticationCode);
+
+    @Operation(
+            summary = "구글 인증 Redirect Link",
+            description = "구글 웹 페이지 로그인을 통해 로그인한 코드를 받을 경우 사용합니다. 일반적으로 사용되지 않는 api",
+            hidden = true
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "인증 후 인증 코드를 담아서 보냅니다.",
+                    content = @Content(
+                            mediaType = MediaType.APPLICATION_JSON_VALUE,
+                            schema = @Schema(implementation = AuthRequestDto.class)
+                    )
+            )
+    })
+    @GetMapping("google/callback")
+    AuthRequestDto redirectGoogleAuth(@RequestParam(name = "code") String authenticationCode);
 }
diff --git a/src/main/java/com/universe/uni/dto/AuthTokenDto.java b/src/main/java/com/universe/uni/dto/AuthTokenDto.java
@@ -2,8 +2,15 @@
 
 import com.fasterxml.jackson.annotation.JsonProperty;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "인증 토큰 DTO")
 public record AuthTokenDto(
-	@JsonProperty("access_token") String accessToken,
-	@JsonProperty("refresh_token") String refreshToken
+        @JsonProperty("access_token")
+        @Schema(description = "인증 토큰", nullable = false)
+        String accessToken,
+        @JsonProperty("refresh_token")
+        @Schema(description = "인증 토큰이 만료 된 경우 갱신 토큰", nullable = true)
+        String refreshToken
 ) {
 }
diff --git a/src/main/java/com/universe/uni/dto/request/AuthRequestDto.java b/src/main/java/com/universe/uni/dto/request/AuthRequestDto.java
@@ -1,6 +1,10 @@
 package com.universe.uni.dto.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "인증 코드 발급을 위한 Request DTO")
 public record AuthRequestDto(
+        @Schema(description = "각 인증 수단으로 받은 인증 코드")
 		String code
 ) {
 }
diff --git a/src/main/java/com/universe/uni/exception/dto/ErrorResponse.java b/src/main/java/com/universe/uni/exception/dto/ErrorResponse.java
@@ -3,16 +3,19 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AccessLevel;
 import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 
 @Getter
 @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
 @JsonInclude(JsonInclude.Include.NON_NULL)
+@Schema(description = "서버 에러 발생시 에러 바디 DTO")
 public class ErrorResponse {
 
 	@JsonProperty("code")
+    @Schema(description = "자체 에러 코드, 별도 문서 혹은 각 api 에러 코드 확인")
 	private final String uniErrorCode;
 
 	public static ErrorResponse businessErrorOf(ErrorType error) {