Skip to content

Commit

Permalink
Merge pull request #68 from team-crews/docs/#63-fix-api-docs
Browse files Browse the repository at this point in the history 
api docs 개선
  • Loading branch information
@jongmee
jongmee authored Sep 5, 2024
2 parents f96af64 + b751dd9 commit 19d2d5f
Show file tree
Hide file tree
Showing 4 changed files with 170 additions and 148 deletions.
85 changes: 50 additions & 35 deletions src/test/java/com/server/crews/api/ApplicationApiDocuments.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,43 +2,34 @@

import static com.epages.restdocs.apispec.RestAssuredRestDocumentationWrapper.document;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;

import com.epages.restdocs.apispec.ResourceSnippetParametersBuilder;
import org.springframework.restdocs.payload.ResponseFieldsSnippet;
import org.springframework.restdocs.restassured.RestDocumentationFilter;

public class ApplicationApiDocuments {
private static final String APPLICATION_API = "application/";

public static RestDocumentationFilter SAVE_APPLICATION_200_DOCUMENT() {
return document(APPLICATION_API + "지원서 저장",
new ResourceSnippetParametersBuilder().description("지원서를 저장한다.")
.requestFields(
fieldWithPath(".id")
.description("지원서 id (최초 저장이 아닐 경우 필요함)")
.optional(),
fieldWithPath(".studentNumber")
.description("학번"),
fieldWithPath(".major")
.description("전공"),
fieldWithPath(".name")
.description("이름"),
fieldWithPath(".answers")
.description("답변 목록")
.optional(),
fieldWithPath(".answers[].answerId")
.description("답변 id")
.optional(),
fieldWithPath(".answers[].questionType")
.description("질문 타입(NARRATIVE, SELECTIVE 중 하나)"),
fieldWithPath(".answers[].questionId")
.description("질문 id"),
fieldWithPath(".answers[].content")
.description("서술형 답안 (NARRATIVE 질문의 경우)")
.optional(),
fieldWithPath(".answers[].choiceId")
.description("선택지 id (SELECTIVE 질문의 경우)")
.optional()));
"지원서를 저장한다.",
requestFields(
fieldWithPath(".id").description("지원서 id (최초 저장이 아닐 경우 필요함)").optional(),
fieldWithPath(".recruitmentCode").description("모집 공고 코드"),
fieldWithPath(".studentNumber").description("학번"),
fieldWithPath(".major").description("전공"),
fieldWithPath(".name").description("지원자 이름"),
fieldWithPath(".answers").description("답변 목록"),
fieldWithPath(".answers[].answerId").description("답변 id").optional(),
fieldWithPath(".answers[].questionType").description("질문 타입(NARRATIVE, SELECTIVE 중 하나)"),
fieldWithPath(".answers[].questionId").description("질문 id"),
fieldWithPath(".answers[].content").description("서술형 답안 (NARRATIVE 질문의 경우)").optional(),
fieldWithPath(".answers[].choiceId").description("선택지 id (SELECTIVE 질문의 경우)").optional()),
applicationDetailsResponseFields());
}

public static RestDocumentationFilter SAVE_APPLICATION_404_DOCUMENT() {
Expand All @@ -47,14 +38,17 @@ public static RestDocumentationFilter SAVE_APPLICATION_404_DOCUMENT() {

public static RestDocumentationFilter GET_APPLICATION_200_DOCUMENT() {
return document(APPLICATION_API + "동아리 관리자 지원서 상세 조회",
new ResourceSnippetParametersBuilder().description("동아리 관리자가 지원서 상세 정보를 조회한다.")
.pathParameters(parameterWithName("application-id").description("지원서 id")));
"동아리 관리자가 지원서 상세 정보를 조회한다.",
pathParameters(
parameterWithName("application-id").description("지원서 id")),
applicationDetailsResponseFields());
}

public static RestDocumentationFilter GET_MY_APPLICATION_200_DOCUMENT() {
return document(APPLICATION_API + "지원자 지원서 상세 조회",
new ResourceSnippetParametersBuilder().description("지원자가 본인의 지원서 상세 정보를 조회한다.")
.queryParameters(parameterWithName("code").description("모집공고 code")));
"지원자가 본인의 지원서 상세 정보를 조회한다.",
queryParameters(parameterWithName("code").description("모집공고 code")),
applicationDetailsResponseFields());
}

public static RestDocumentationFilter GET_MY_APPLICATION_204_DOCUMENT() {
Expand All @@ -63,16 +57,37 @@ public static RestDocumentationFilter GET_MY_APPLICATION_204_DOCUMENT() {

public static RestDocumentationFilter GET_APPLICATIONS_200_DOCUMENT() {
return document(APPLICATION_API + "지원서 목록 조회",
new ResourceSnippetParametersBuilder().description("지원서 목록을 조회한다."));
"지원서 목록을 조회한다.",
responseFields(
fieldWithPath("[].id").description("지원서 id"),
fieldWithPath("[].studentNumber").description("학번"),
fieldWithPath("[].name").description("지원자 이름"),
fieldWithPath("[].major").description("전공"),
fieldWithPath("[].outcome").description("지원 결과 (PENDING, PASS, FAIL 중 하나)")));
}

public static RestDocumentationFilter EVALUATE_APPLICATIONS_200_DOCUMENT() {
return document(APPLICATION_API + "지원서 평가",
new ResourceSnippetParametersBuilder().description("지원서를 평가한다.")
.requestFields(fieldWithPath(".passApplicationIds").description("합격 지원서 id 목록")));
"지원서를 평가를 저장한다.",
requestFields(
fieldWithPath(".passApplicationIds").description("합격 지원서 id 목록")));
}

public static RestDocumentationFilter EVALUATE_APPLICATIONS_400_DOCUMENT() {
return document(APPLICATION_API + "평가 및 결과 발표 완료된 모집 공고의 지원서 평가");
}

private static ResponseFieldsSnippet applicationDetailsResponseFields() {
return responseFields(
fieldWithPath(".id").description("지원서 id"),
fieldWithPath(".studentNumber").description("학번"),
fieldWithPath(".major").description("전공"),
fieldWithPath(".name").description("지원자 이름"),
fieldWithPath(".answers").description("답변 목록"),
fieldWithPath(".answers[].answerId").description("답변 id"),
fieldWithPath(".answers[].type").description("답변 타입(NARRATIVE, SELECTIVE 중 하나)"),
fieldWithPath(".answers[].choiceId").description("선택지 id (SELECTIVE 질문의 경우)").optional(),
fieldWithPath(".answers[].content").description("서술형 답안 (NARRATIVE 질문의 경우)").optional(),
fieldWithPath(".answers[].questionId").description("질문 id"));
}
}
70 changes: 30 additions & 40 deletions src/test/java/com/server/crews/api/AuthApiDocuments.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,55 +2,41 @@

import static com.epages.restdocs.apispec.RestAssuredRestDocumentationWrapper.document;
import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
import static org.springframework.restdocs.headers.HeaderDocumentation.requestHeaders;
import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;

import com.epages.restdocs.apispec.ResourceSnippetParametersBuilder;
import org.springframework.restdocs.restassured.RestDocumentationFilter;

public class AuthApiDocuments {
private static final String AUTH_API = "auth/";

public static RestDocumentationFilter LOGIN_ADMIN_200_DOCUMENT() {
return document(AUTH_API + "동아리 운영진 로그인",
new ResourceSnippetParametersBuilder().description("동아리 운영진(admin)이 로그인한다.")
.requestFields(
fieldWithPath(".clubName")
.description("동아리 이름"),
fieldWithPath(".password")
.description("비밀번호"))
.responseFields(
fieldWithPath(".adminId")
.description("운영진 id"),
fieldWithPath(".accessToken")
.description("access token"),
fieldWithPath(".recruitmentProgress")
.description(
"모집 공고 상태 (READY: 모집 공고 작성 중, IN_PROGRESS: 모집 중, COMPLETION: 평가 중, ANNOUNCED: 이메일 전송 완료)"),
fieldWithPath(".recruitmentId")
.description("모집 공고 id (없다면 null)"))
.responseHeaders(headerWithName("Cookie")
.description("리프레시 토큰")));
"동아리 운영진(admin)이 로그인한다.",
requestFields(
fieldWithPath(".clubName").description("동아리 이름"),
fieldWithPath(".password").description("비밀번호")),
responseFields(
fieldWithPath(".username").description("동아리 이름"),
fieldWithPath(".accessToken").description("access token")),
responseHeaders(
headerWithName("Set-Cookie").description("리프레시 토큰")));
}

public static RestDocumentationFilter LOGIN_APPLICANT_200_DOCUMENT() {
return document(AUTH_API + "지원자 로그인",
new ResourceSnippetParametersBuilder().description("지원자(applicant)가 로그인한다.")
.requestFields(
fieldWithPath(".recruitmentCode")
.description("모집 공고 코드"),
fieldWithPath(".email")
.description("이메일"),
fieldWithPath(".password")
.description("비밀번호"))
.responseFields(
fieldWithPath(".applicantId")
.description("지원자 id"),
fieldWithPath(".accessToken")
.description("access token"),
fieldWithPath(".recruitmentProgress")
.description("모집 공고 상태 (IN_PROGRESS: 모집 중, COMPLETION: 평가 중)"),
fieldWithPath(".applicationId")
.description("지원서 id (없다면 null)")));
"지원자(applicant)가 로그인한다.",
requestFields(
fieldWithPath(".email").description("이메일"),
fieldWithPath(".password").description("비밀번호")),
responseFields(
fieldWithPath(".username").description("지원자 email"),
fieldWithPath(".accessToken").description("access token")),
responseHeaders(
headerWithName("Set-Cookie").description("리프레시 토큰")));
}

public static RestDocumentationFilter LOGIN_ADMIN_400_DOCUMENT() {
Expand All @@ -59,14 +45,18 @@ public static RestDocumentationFilter LOGIN_ADMIN_400_DOCUMENT() {

public static RestDocumentationFilter REFRESH_TOKEN_200_DOCUMENT() {
return document(AUTH_API + "토큰 재발급",
new ResourceSnippetParametersBuilder().description("access token을 재발급 받는다.")
.requestHeaders(headerWithName("Cookie")
.description("리프레시 토큰")));
"access token을 재발급 받는다.",
requestHeaders(
headerWithName("Cookie").description("리프레시 토큰")),
responseFields(
fieldWithPath(".accessToken").description("access token")));
}

public static RestDocumentationFilter LOGOUT_200_DOCUMENT() {
return document(AUTH_API + "로그아웃",
new ResourceSnippetParametersBuilder().description("로그아웃한다."));
"로그아웃한다.",
responseHeaders(
headerWithName("Set-Cookie").description("만료된 쿠키")));
}

public static RestDocumentationFilter AUTHORIZE_401_DOCUMENT() {
Expand Down
2 changes: 1 addition & 1 deletion src/test/java/com/server/crews/api/AuthApiTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ void refreshAccessToken() {
// when
ExtractableResponse<Response> response = RestAssured.given(spec).log().all()
.filter(AuthApiDocuments.REFRESH_TOKEN_200_DOCUMENT())
.cookie("refreshToken", refreshToken)
.header("Cookie", "refreshToken=" + refreshToken)
.contentType(MediaType.APPLICATION_JSON_VALUE)
.body(adminLoginRequest)
.when().post("/auth/refresh")
Expand Down
Loading

0 comments on commit 19d2d5f

Please sign in to comment.