[Week8] Make API Docs, Docker image #2

JamieShin0201 · 2021-03-15T10:28:46Z

해야 할 일

Javadoc 작성하기
API 문서 만들기
Docker image 만들기

벌써 8주차네요 ㅎ.ㅎ 이번 한주도 잘 부탁드립니다^_^

상품 서비스가 어떤 역할을 하는지 설명하기 위해 주석을 작성하였습니다.

상품 컨트롤러가 어떤 역할을 하는지 설명하기 위해 주석을 작성하였습니다.

세션 컨트롤러가 어떤 역할을 하는지 설명하기 위해 주석을 작성하였습니다.

회원 컨트롤러, 서비스가 어떤 역할을 하는지 설명하기 위해 주석을 작성하였습니다.

app/src/main/java/com/codesoom/assignment/application/UserService.java

app/src/main/java/com/codesoom/assignment/application/ProductService.java

johngrib

54f79fe 커밋 메시지가 좋습니다.

이렇게 작성해도 괜찮았을 거에요.

상품 서비스의 역할을 설명하였습니다.

app/src/main/java/com/codesoom/assignment/application/ProductService.java

johngrib

그 사이에 주석 작성 실력이 일취월장하셨군요.

app/src/main/java/com/codesoom/assignment/controllers/ProductController.java

클래스의 구현 내용이 주석에 포함되어 있었습니다. 구현 내용은 언제든 변할 수 있어 주석에 작성하는 것이 올바르지 않다고 생각합니다. 그래서 클래스의 핵심 역할을 제외한 설명들을 지웠습니다.

인증 서비스의 역할을 설명하였습니다.

상품의 역할을 설명하였습니다.

회원의 역할을 설명하였습니다.

app/src/main/java/com/codesoom/assignment/domain/Product.java

app/src/main/java/com/codesoom/assignment/domain/User.java

반복되는 단어로 주석을 한번에 이해하기 어려웠습니다. 그래서 반복된 단어를 의미가 비슷한 다른 단어로 변경하였습니다.

johngrib

669d9f6 좋습니다. 그러나 마지막 줄은 없어도 괜찮았을 거에요.

johngrib

e57fa1e 이런 경우엔 커밋 메시지 타이틀을 다음과 같이 적고 본문은 적지 않아도 괜찮을 것 같습니다.

인증 서비스의 역할을 설명하라

app/src/main/java/com/codesoom/assignment/controllers/UserController.java

반복되는 단어로 주석을 한번에 이해하기 어려웠습니다. 그래서 반복된 단어를 의미가 비슷한 다른 단어로 변경하였습니다.

johngrib

커밋 메시지와 변경 내용이 모두 좋습니다. 기분 좋은 커밋입니다.

app/src/main/java/com/codesoom/assignment/utils/JwtUtil.java

app/src/main/java/com/codesoom/assignment/errors/ProductNotFoundException.java

app/src/main/java/com/codesoom/assignment/errors/UserEmailDuplicationException.java

app/src/main/java/com/codesoom/assignment/errors/UserNotFoundException.java

REST Api 문서작성을 위해 Spring REST Docs와 관련된 의존성을 추가하였습니다.

현재 프로젝트에 설정된 자바8 버전에서는 공백을 확인하는 메소드(isBlank)를 사용할 수 없습니다. 따라서, 자바 버전을 8 -> 11로 변경하였습니다.

한줄에 모든 속성이 표현되어 한번에 파악하기가 어려웠습니다. prettyPrint 설정을 추가하여 한줄에 하나의 속성을 표현하도록 변경하였습니다.

JamieShin0201 · 2021-03-18T11:13:11Z

app/src/docs/asciidoc/index.adoc

+====== http
+
+include::{path}/http-request.adoc[]


위에 이미 http request에 대한 정보가 제공되니 이 부분은 지워도 될 것 같네요.

JamieShin0201 · 2021-03-18T11:14:35Z

app/src/test/java/com/codesoom/assignment/controllers/ProductControllerTest.java

+                .andExpect(content().string(containsString("쥐돌이")))
+                .andDo(document("get-products",
+                        responseFields(
+                                fieldWithPath("[].id").type(NUMBER).description("상품 식별자"),
+                                fieldWithPath("[].name").type(STRING).description("상품 이름"),
+                                fieldWithPath("[].maker").type(STRING).description("상품 제조사"),
+                                fieldWithPath("[].price").type(NUMBER).description("상품 가격"),
+                                fieldWithPath("[].imageUrl").type(STRING).optional().description("상품 이미지")
+                        ))
+                )
+        ;


REST docs를 위한 코드들은 따로 분리해도 좋을 것 같네요.

네. 배열이나 리스트로 다른 곳에 선언하는 방법을 사용해 보세요.

johngrib

45384ae 내용은 사실이지만 필요 이상으로 자세한 설명입니다. 주석을 올바른 형식으로 고쳐라 정도가 적당해요.

johngrib

c3ea2c6 개발과 관련된 문서의 종류는 다양합니다. 어떤 문서인지 명시해주면 바람직할 거에요.

다음과 같이 수정하면 어떨까요?
API 문서 작성을 위해 asciidoctor 의존성을 추가하라

johngrib

de120c5

나쁘지 않은 주석이지만 isBlank를 위해 11을 선택한 것 같이 좀 미묘한 느낌이 듭니다. isBlank를 해결하기 위해서라면 11이 아니라 13도 15도 가능했겠죠.

app/build.gradle

회원 요청 정보 클래스들에 기본생성자가 없어 데이터 바인딩에 문제가 있었습니다.

테스트 코드 안에 문서작성을 위한 코드가 같이 있어 클래스가 복잡했습니다. 그래서, 두 코드를 분리하였습니다. 문서작성을 위한 코드에 중복된 값들이 많았습니다. 중복된 값들을 없애기 위해 Item, ItemProvider 클래스를 생성하여 요청, 응답, 헤더, 파라미터 값들을 관리하였습니다.

JamieShin0201 · 2021-03-19T12:33:14Z

de120c5

나쁘지 않은 주석이지만 isBlank를 위해 11을 선택한 것 같이 좀 미묘한 느낌이 듭니다. isBlank를 해결하기 위해서라면 11이 아니라 13도 15도 가능했겠죠.

공감합니다.. 8, 11, 13, 15 차이를 잘 모르는데 학습을 해야할 것 같습니다.

JamieShin0201

c99d01b

코드를 분리하는 것과 중복된 값들을 관리하는 것을 따로 분리해서 작업해도 좋았을 것 같습니다.

종립님 블로그 참고해서 생성기(요청, 응답, 헤더, 파라미터)를 만들었습니다.

요청 필드가 필수값인지 아닌지에 대한 정보를 사용자에게 제공하기 위해 사용자 지정 템플릿을 작성하였습니다.

johngrib · 2021-03-20T13:34:26Z

app/src/test/java/com/codesoom/assignment/docs/ProductDocumentation.java

+                Item.of("[].id", NUMBER, "상품 식별자"),
+                Item.of("[].name", STRING, "상품 이름"),
+                Item.of("[].maker", STRING, "상품 제조사"),
+                Item.of("[].price", NUMBER, "상품 가격"),
+                Item.of("[].imageUrl", STRING, "상품 이미지", State.OPTIONAL)


여기에서 [].은 상위의 of("[]", of("id", NUMBER, "상품 식별자"), of("name", STRING, "상품 이름"), ... ) 처럼 한 단계 더 분리할 수 있습니다.

johngrib · 2021-03-20T13:35:05Z

app/src/test/java/com/codesoom/assignment/controllers/SessionControllerTest.java

    }
-
+    


불필요한 공백 문자가 있군요.

johngrib · 2021-03-20T13:35:36Z

app/src/test/java/com/codesoom/assignment/docs/UserDocumentation.java

-                        fieldWithPath("email").type(STRING).description("회원 이메일"),
-                        fieldWithPath("name").type(STRING).description("회원 이름"),
-                        fieldWithPath("password").type(STRING).description("회원 비밀번호")
+                        new ItemProvider(EMAIL, NAME, PASSWORD).toFields()


좋은 시도입니다.

JamieShin0201 · 2021-03-21T12:03:49Z

아직 [] 분리와 파일 공백제거, 주간회고 작성을 하지 못했습니다! ㅠ.ㅠ

이번 한주도 많이 배웠습니다. 너무 감사했습니다 ㅎ.ㅎ

johngrib · 2021-03-21T12:19:53Z

아직 [] 분리와 파일 공백제거, 주간회고 작성을 하지 못했습니다! ㅠ.ㅠ

이번 한주도 많이 배웠습니다. 너무 감사했습니다 ㅎ.ㅎ

많이 배우셨다니 저도 기쁩니다.

johngrib

주간 회고를 작성해 공유해주세요. 한 주간 고생 많으셨습니다.

* refactor: 패키지 구조를 hexagonal-architecture 구조로 변경 * refactor: HelloController 삭제

상품 서비스에 주석을 작성하라

54f79fe

상품 서비스가 어떤 역할을 하는지 설명하기 위해 주석을 작성하였습니다.

JamieShin0201 changed the base branch from main to JamieShin0201 March 15, 2021 10:29

JamieShin0201 added 3 commits March 15, 2021 19:42

상품 컨트롤러에 주석을 작성하라

695f7ab

상품 컨트롤러가 어떤 역할을 하는지 설명하기 위해 주석을 작성하였습니다.

세션 컨트롤러에 주석을 작성하라

7592bf0

세션 컨트롤러가 어떤 역할을 하는지 설명하기 위해 주석을 작성하였습니다.

회원 컨트롤러, 서비스에 주석을 작성하라

2c51e64

회원 컨트롤러, 서비스가 어떤 역할을 하는지 설명하기 위해 주석을 작성하였습니다.

JamieShin0201 commented Mar 15, 2021

View reviewed changes

app/src/main/java/com/codesoom/assignment/application/UserService.java Outdated Show resolved Hide resolved

JamieShin0201 commented Mar 15, 2021

View reviewed changes

app/src/main/java/com/codesoom/assignment/application/ProductService.java Outdated Show resolved Hide resolved

johngrib reviewed Mar 15, 2021

View reviewed changes

app/src/main/java/com/codesoom/assignment/application/ProductService.java Outdated Show resolved Hide resolved

johngrib reviewed Mar 15, 2021

View reviewed changes

app/src/main/java/com/codesoom/assignment/controllers/ProductController.java Outdated Show resolved Hide resolved

JamieShin0201 added 4 commits March 16, 2021 17:52

인증 서비스에 주석을 작성하라

e57fa1e

인증 서비스의 역할을 설명하였습니다.

상품에 주석을 작성하라

4e25ed1

상품의 역할을 설명하였습니다.

회원에 주석을 작성하라

6572f0d

회원의 역할을 설명하였습니다.

JamieShin0201 commented Mar 16, 2021

View reviewed changes

app/src/main/java/com/codesoom/assignment/domain/Product.java Outdated Show resolved Hide resolved

app/src/main/java/com/codesoom/assignment/domain/User.java Outdated Show resolved Hide resolved

app/src/main/java/com/codesoom/assignment/domain/User.java Outdated Show resolved Hide resolved

회원 컨트롤러의 수정 요청 주석을 읽기 좋게 변경하라

15e8889

반복되는 단어로 주석을 한번에 이해하기 어려웠습니다. 그래서 반복된 단어를 의미가 비슷한 다른 단어로 변경하였습니다.

johngrib reviewed Mar 16, 2021

View reviewed changes

app/src/main/java/com/codesoom/assignment/controllers/UserController.java Show resolved Hide resolved

JamieShin0201 added 5 commits March 17, 2021 18:38

주석 끝에 마침표를 추가하라

ce51f77

PasswordEncoder에 대한 설명을 올바르게 변경하라

732901b

주석에 반복되는 단어를 읽기 좋게 변경하라

6755dd0

반복되는 단어로 주석을 한번에 이해하기 어려웠습니다. 그래서 반복된 단어를 의미가 비슷한 다른 단어로 변경하였습니다.

JWT 도구의 역할을 설명하라

4e95066

주석이 없는 클래스들을 설명하라

854f805

johngrib reviewed Mar 17, 2021

View reviewed changes

JamieShin0201 added 5 commits March 18, 2021 19:13

주석의 끝에 마침표를 작성하라

45384ae

JwtUtil encode메소드에 대한 설명을 보다 정확하게 변경하라

3becb82

버전관리가 필요하지 않은 폴더를 .gitignore에 추가하라

26b7eeb

문서작성을 위한 의존성을 추가하라

c3ea2c6

REST Api 문서작성을 위해 Spring REST Docs와 관련된 의존성을 추가하였습니다.

자바 버전을 변경하라

de120c5

현재 프로젝트에 설정된 자바8 버전에서는 공백을 확인하는 메소드(isBlank)를 사용할 수 없습니다. 따라서, 자바 버전을 8 -> 11로 변경하였습니다.

JamieShin0201 added 2 commits March 18, 2021 19:31

상품과 관련된 REST API 문서를 작성하라

f0156cf

REST API 문서의 요청, 응답 형식을 보기 좋게 변경하라

2837aed

한줄에 모든 속성이 표현되어 한번에 파악하기가 어려웠습니다. prettyPrint 설정을 추가하여 한줄에 하나의 속성을 표현하도록 변경하였습니다.

JamieShin0201 commented Mar 18, 2021

View reviewed changes

johngrib reviewed Mar 18, 2021

View reviewed changes

app/build.gradle Show resolved Hide resolved

JamieShin0201 added 6 commits March 19, 2021 18:32

기본 생성자를 추가하라

9ab2d7c

회원 요청 정보 클래스들에 기본생성자가 없어 데이터 바인딩에 문제가 있었습니다.

회원 REST API 문서를 작성하라

eb32307

API 문서에 중복된 내용을 삭제하라

ef3c79b

API 문서의 요청 URL을 올바르게 변경하라

a71acda

세션 REST API 문서를 작성하라

1061205

JamieShin0201 commented Mar 19, 2021

View reviewed changes

JamieShin0201 added 4 commits March 20, 2021 00:19

테스트 코드와 문서작성 코드를 분리하라

137436b

API 문서작성 코드에서 중복된 값을 제거하라

390d5b8

불필요한 공백라인을 삭제하라

349c388

API 요청 필드에 대한 사용자 지정 템플릿을 작성하라

562e002

요청 필드가 필수값인지 아닌지에 대한 정보를 사용자에게 제공하기 위해 사용자 지정 템플릿을 작성하였습니다.

johngrib reviewed Mar 20, 2021

View reviewed changes

JamieShin0201 added 2 commits March 21, 2021 21:00

Maria DB 의존성을 추가하라

7dc74f1

Maria DB를 설정하라

1120056

johngrib reviewed Mar 21, 2021

View reviewed changes

johngrib merged commit c2b48ea into CodeSoom:JamieShin0201 Mar 22, 2021

hannut91 pushed a commit that referenced this pull request Dec 27, 2022

(#2) Hexagonal Architecture를 적용한다

8d22edc

* refactor: 패키지 구조를 hexagonal-architecture 구조로 변경 * refactor: HelloController 삭제

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Week8] Make API Docs, Docker image #2

[Week8] Make API Docs, Docker image #2

JamieShin0201 commented Mar 15, 2021 •

edited

johngrib left a comment •

edited

johngrib left a comment

johngrib left a comment

johngrib left a comment

johngrib left a comment

JamieShin0201 Mar 18, 2021 •

edited

JamieShin0201 Mar 18, 2021 •

edited

johngrib Mar 18, 2021

johngrib left a comment

johngrib left a comment

johngrib left a comment

JamieShin0201 commented Mar 19, 2021

JamieShin0201 left a comment •

edited

johngrib Mar 20, 2021

johngrib Mar 20, 2021

johngrib Mar 20, 2021

JamieShin0201 commented Mar 21, 2021

johngrib commented Mar 21, 2021

johngrib left a comment

		====== http

		include::{path}/http-request.adoc[]

[Week8] Make API Docs, Docker image #2

[Week8] Make API Docs, Docker image #2

Conversation

JamieShin0201 commented Mar 15, 2021 • edited

해야 할 일

johngrib left a comment • edited

Choose a reason for hiding this comment

johngrib left a comment

Choose a reason for hiding this comment

johngrib left a comment

Choose a reason for hiding this comment

johngrib left a comment

Choose a reason for hiding this comment

johngrib left a comment

Choose a reason for hiding this comment

JamieShin0201 Mar 18, 2021 • edited

Choose a reason for hiding this comment

JamieShin0201 Mar 18, 2021 • edited

Choose a reason for hiding this comment

johngrib Mar 18, 2021

Choose a reason for hiding this comment

johngrib left a comment

Choose a reason for hiding this comment

johngrib left a comment

Choose a reason for hiding this comment

johngrib left a comment

Choose a reason for hiding this comment

JamieShin0201 commented Mar 19, 2021

JamieShin0201 left a comment • edited

Choose a reason for hiding this comment

johngrib Mar 20, 2021

Choose a reason for hiding this comment

johngrib Mar 20, 2021

Choose a reason for hiding this comment

johngrib Mar 20, 2021

Choose a reason for hiding this comment

JamieShin0201 commented Mar 21, 2021

johngrib commented Mar 21, 2021

johngrib left a comment

Choose a reason for hiding this comment

JamieShin0201 commented Mar 15, 2021 •

edited

johngrib left a comment •

edited

JamieShin0201 Mar 18, 2021 •

edited

JamieShin0201 Mar 18, 2021 •

edited

JamieShin0201 left a comment •

edited