티스토리

API 문서

Table of Contents

POST /api/v2/users/new - 회원가입
POST /api/v2/users/login - 회원가입

`POST /api/v2/users/new` - 회원가입

HTTP request: ../../../build/generated-snippets/users/createSuccess/http-request.adoc

HTTP response: ../../../build/generated-snippets/users/createSuccess/http-response.adoc

`POST /api/v2/users/login` - 회원가입

HTTP request: ../../../build/generated-snippets/users/loginSuccess/http-request.adoc

HTTP response: ../../../build/generated-snippets/users/loginSuccess/http-response.adoc

	plugins {
	id "org.asciidoctor.jvm.convert" version "3.3.2" // AsciiDoc 문서를 HTML, PDF, ePub 등 다양한 포맷으로 변환
	}

	configurations {
	asciidoctorExt // asciidoctorExt에 대한 종속성 구성 선언
	}

	dependencies {
	// Spring REST Docs
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
	// Spring REST Docs로 생성된 AsciiDoc 형식의 문서를 최종적으로 HTML이나 PDF 같은 문서 파일로 변환하기 위해 사용되는 라이브러리
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
	// MockMvc를 사용한 테스트에서 API 문서를 생성할 때 사용
	// MockMvc: Spring MVC 애플리케이션을 실제 서버 없이 테스트할 수 있게 해주는 도구
	testImplementation 'org.springframework.restdocs:spring-restdocs-restassured'
	// REST Assured를 사용한 API 테스트에서 문서를 생성할 때 사용
	// REST Assured: REST API를 테스트하기 위해 자주 사용되는 라이브러리, HTTP 요청 및 응답을 간단하게 작성하고 확인할 수 있음
	}

	ext { // 스니펫 생성 디렉토리 설정
	snippetsDir = file('build/generated-snippets')
	}

	test {
	outputs.dir snippetsDir // 테스트가 수행된 후 Spring REST Docs에서 생성한 스니펫들이 이 디렉토리에 저장
	}

	asciidoctor { // asciidoctor 테스크 설정
	inputs.dir snippetsDir
	// Spring REST Docs가 테스트 실행 후에 생성하는 스니펫 파일(예: 요청/응답, cURL 명령어 등)이 저장되는 디렉토리
	configurations 'asciidoctorExt'
	// asciidoctor 작업에 대해 추가적인 설정을 적용하기 위해 사용되는 설정
	// Spring REST Docs가 테스트를 통해 생성한 스니펫을 가져와, Asciidoctor가 문서로 변환할 수 있도록 함
	dependsOn test
	// test 테스크가 먼저 실행된 후에 asciidoctor 테스크가 실행되도록 하여,
	// 테스트가 완료된 후 생성된 스니펫을 사용해 API 문서를 빌드할 수 있도록 보장
	}

	task copyDocument(type: Copy) {
	dependsOn asciidoctor
	from file("build/docs/asciidoc")
	// resources/static/docs로 복사하여 서버가 돌아가고 있을때 /docs/index.html로 접속하면 볼수 있음
	into file("src/main/resources/static/docs")
	}

	build {
	dependsOn copyDocument
	}

	bootJar {
	dependsOn asciidoctor
	from("${asciidoctor.outputDir}/html5") {
	into 'static/docs'
	}
	}

	@Configuration
	public class WebMvcConfig implements WebMvcConfigurer {
	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
	registry.addResourceHandler("/docs/**").addResourceLocations("classpath:/static/docs/");
	}
	}

	@SpringBootTest
	@ExtendWith({RestDocumentationExtension.class})
	// RestDocumentationExtension: Spring REST Docs의 기능을 테스트에 확장하여 API 문서화를 자동으로 할 수 있게 함
	// RestDocumentationContextProvider 객체를 제공하여 MockMvc 설정 시 REST Docs 문서화를 할 수 있게 도와줌
	// 테스트 실행 시 REST Docs 관련 설정을 수동으로 추가할 수 있도록 도와줌
	@AutoConfigureMockMvc
	class UserControllerTest {

	@Autowired
	MockMvc mockMvc;
	@Autowired
	ObjectMapper objectMapper;
	@MockBean
	UserService userService;

	@BeforeEach
	void setUp(WebApplicationContext webApplicationContext,
	RestDocumentationContextProvider restDocumentation) {
	this.mockMvc = MockMvcBuilders.webAppContextSetup(
	webApplicationContext) // webApplicationContext 기반 Mock 객체 생성
	.apply(documentationConfiguration(
	restDocumentation)) // REST Docs의 문서화를 위한 설정을 추가
	.alwaysDo(print())
	.alwaysDo(document("users/{method-name}",
	preprocessRequest(prettyPrint()),
	preprocessResponse(prettyPrint())))
	// REST Docs 문서화 작업을 자동으로 실행
	// {method-name}을 통해 각 테스트 메서드 이름에 따라 문서화 파일을 생성
	.addFilters(new CharacterEncodingFilter("UTF-8", true))
	.build();
	}

	@Test
	@DisplayName("회원 가입: 성공")
	void createSuccess() throws Exception {
	// given
	SignUpRequestDTO signUpDto = SignUpRequestDTO.builder()
	.userType("MSGS")
	.email("new@email.com")
	.phone("01023698741")
	.nickname("name")
	.password("newnew123!")
	.confirmPassword("newnew123!")
	.build();

	// when
	ResultActions result = mockMvc.perform(post("/api/v2/users/new")
	.contentType(MediaType.APPLICATION_JSON)
	.content(objectMapper.writeValueAsString(signUpDto)));
	// objectMapper.writeValueAsString(signUpDto)
	// DTO 객체를 JSON 문자열로 변환한 후, 이를 HTTP 요청으로 보냄
	// signUpDto의 값들이 변형되지 않지만, userService.create()가 호출될 때는 새로운 인스턴스가 생성

	// then
	result.andExpect(status().isCreated());
	}
	}

티스토리

[1년 후 마실가실] API 문서화 도구 - Spring REST Docs

[1년 후 마실가실] API 문서화 도구 - Spring REST Docs

API 문서

`POST /api/v2/users/new` - 회원가입

`POST /api/v2/users/login` - 회원가입

[1년 후 마실가실] API 문서화 도구 - Spring REST Docs

[1년 후 마실가실] API 문서화 도구 - Spring REST Docs

API 문서

POST /api/v2/users/new - 회원가입

POST /api/v2/users/login - 회원가입

`POST /api/v2/users/new` - 회원가입

`POST /api/v2/users/login` - 회원가입