diff --git a/hehe-board/src/docs/asciidoc/index.adoc b/hehe-board/src/docs/asciidoc/index.adoc new file mode 100644 index 000000000..6e7cb2e8d --- /dev/null +++ b/hehe-board/src/docs/asciidoc/index.adoc @@ -0,0 +1,82 @@ += Spring REST Docs 가이드 +:doctype: book +:icons: font +:source-highlighter: coderay +:toc: left +:toc-title: 목차 +:toclevels: 3 +:sectlinks: +:sectnums: + +== 개요 +이 API문서는 'Spring REST Docs 가이드' 프로젝트의 산출물입니다. + + +=== API 서버 경로 +[cols="2,5,3"] +|==== +|환경 |DNS |비고 +|개발(dev) | link:[] |API 문서 제공 +|베타(beta) | link:[] |API 문서 제공 +|운영(prod) | link:[] |API 문서 미제공 +|==== + +[NOTE] +==== +해당 프로젝트 API문서는 개발환경까지 노출되는 것을 권장합니다. + +==== + +[CAUTION] +==== +운영환경에 노출될 경우 보안 관련 문제가 발생할 수 있습니다. +==== + +=== 응답형식 +프로젝트는 다음과 같은 응답형식을 제공합니다. + +==== 정상(200, OK) + +|==== +|응답데이터가 없는 경우|응답데이터가 있는 경우 + +a|[source,json] +---- +{ + "code": "0000", // 정상인 경우 '0000' + "data": null +} +---- + +a|[source,json] +---- +{ + "code": "0000", // 정상인 경우 '0000' + "data": { + "name": "honeymon-enterprise" + } +} +---- +|==== + +==== 상태코드(HttpStatus) +응답시 다음과 같은 응답상태 헤더, 응답코드 및 응답메시지를 제공합니다. + +[cols="3,1,3,3"] +|==== +|HttpStatus |코드 |메시지 |설명 + +|`OK(200)` |`0000` |"OK" |정상 응답 +|`INTERNAL_SERVER_ERROR(500)`|`S5XX` |"알 수 없는 에러가 발생했습니다. 관리자에게 문의하세요." |서버 내부 오류 +|`FORBIDDEN(403)`|`C403` |"[AccessDenied] 잘못된 접근입니다." |비인가 접속입니다. +|`BAD_REQUEST(400)`|`C400` |"잘못된 요청입니다. 요청내용을 확인하세요." |요청값 누락 혹은 잘못된 기입 +|`NOT_FOUND(404)`|`C404` |"상황에 따라 다름" |요청값 누락 혹은 잘못된 기입 + +|==== + +== API + +// 유저 +include::user.adoc[] + +// 게시글 +include::post.adoc[] \ No newline at end of file diff --git a/hehe-board/src/docs/asciidoc/post.adoc b/hehe-board/src/docs/asciidoc/post.adoc new file mode 100644 index 000000000..7bcb6be45 --- /dev/null +++ b/hehe-board/src/docs/asciidoc/post.adoc @@ -0,0 +1,67 @@ +ifndef::snippets[] +:snippets: ./build/generated-snippets +endif::[] + +== 게시글(Post) +Post 에 대한 등록 기능을 제공합니다. + +=== 유저 등록 +유저를 새롭게 등록합다. + +|==== +|속성 |설명 + +|`name` |사용자 이름(문자열 입력) +|`age` |사용자 나이(최소: 1, 최대: 120) +|`hobby` |사용자 취미(문자열 입력) + +|==== + +=== 생성 + +[discrete] +==== 요청 +include::{snippets}/post-save/curl-request.adoc[] +include::{snippets}/post-save/httpie-request.adoc[] +include::{snippets}/post-save/http-request.adoc[] +include::{snippets}/post-save/request-fields.adoc[] + +[discrete] +==== 응답 +include::{snippets}/post-save/http-response.adoc[] +include::{snippets}/post-save/response-fields.adoc[] + +=== 단일 조회 +==== 요청 +include::{snippets}/post-find/curl-request.adoc[] +include::{snippets}/post-find/httpie-request.adoc[] +include::{snippets}/post-find/http-request.adoc[] + +[discrete] +==== 응답 +include::{snippets}/post-find/http-response.adoc[] +include::{snippets}/post-find/response-fields.adoc[] + +=== 리스트 조회 +==== 요청 +include::{snippets}/post-get/curl-request.adoc[] +include::{snippets}/post-get/httpie-request.adoc[] +include::{snippets}/post-get/http-request.adoc[] + +[discrete] +==== 응답 +include::{snippets}/post-get/http-response.adoc[] +include::{snippets}/post-get/response-fields.adoc[] + +=== 수정 +==== 요청 +include::{snippets}/post-update/curl-request.adoc[] +include::{snippets}/post-update/httpie-request.adoc[] +include::{snippets}/post-update/http-request.adoc[] +include::{snippets}/post-update/request-fields.adoc[] + + +[discrete] +==== 응답 +include::{snippets}/post-update/http-response.adoc[] +include::{snippets}/post-update/response-fields.adoc[] \ No newline at end of file diff --git a/hehe-board/src/docs/asciidoc/user.adoc b/hehe-board/src/docs/asciidoc/user.adoc new file mode 100644 index 000000000..2e7b53a8a --- /dev/null +++ b/hehe-board/src/docs/asciidoc/user.adoc @@ -0,0 +1,31 @@ +ifndef::snippets[] +:snippets: ./build/generated-snippets +endif::[] + +== 유저(User) +User 에 대한 등록 기능을 제공합니다. + +=== 유저 등록 +유저를 새롭게 등록합다. + +|==== +|속성 |설명 + +|`name` |사용자 이름(문자열 입력) +|`age` |사용자 나이(최소: 1, 최대: 120) +|`hobby` |사용자 취미(문자열 입력) + +|==== + + +[discrete] +==== 요청 +include::{snippets}/member-save/curl-request.adoc[] +include::{snippets}/member-save/httpie-request.adoc[] +include::{snippets}/member-save/http-request.adoc[] +include::{snippets}/member-save/request-fields.adoc[] + +[discrete] +==== 응답 +include::{snippets}/member-save/http-response.adoc[] +include::{snippets}/member-save/response-fields.adoc[] \ No newline at end of file