[TIL] 221209 - JPA : REST-API, API 문서화

SpringBoot Part4 (5) 

 

 

학습목표

• 엔티티 (주문관리 vs 게시판)
• API 개발 (JUnit, Lombok, OSIV)
• API 문서화 (레스트 닥스, 스웨거)

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <scope>test</scope>
<!-- 레스트 닥스 -->
</dependency>

 

 

주문관리 API 개발

• 주문생성(POST)
• 주문조회(GET)
  1. 리스트(PAGING)
  2. 단건 (ONE)

 

Service layer

 

converter

entity를 Transaction 묶음 밖에 까지 끌고 나가는 것은 좋지 않다. entity는 RDB와 어느 정도 통신을 하고 있는 객체이기 때문에 entity가 묶음 밖으로 빠져나가면 예상치 못한 곳에서 쿼리가 발생할 수 있기 때문이다. (OSIV)

→ dto 객체를 만들어서 통신한다.

 

Orderservice.class

@Service
public class OrderService {

    @Autowired
    private OrderRepository orderRepository;

    @Autowired
    private OrderConverter orderConverter;

    @Transactional
    public String save(OrderDto orderDto) {
        // 1. dto -> entity 변환 (준영속)
        Order order = orderConverter.convertOrder(orderDto);
        // 2. orderRepository.save(entity) -> 영속화
        Order entity = orderRepository.save(order);
        // 3. 결과 반환
        return entity.getUuid(); // entity 객체가 아닌 id만 반
    }

    @Transactional
    public OrderDto findOne(String uuid){
        // 1. 조회를 위한 키값 인자로 받기
        // 2. orderRepository.findByIdd(uuid) -> 조회(영속화된 엔티티)
        OrderDto orderDto = orderRepository.findById(uuid)
                .map(orderConverter::convertOrderDto) // 3. entity -> dto
                .orElseThrow(() -> new IllegalArgumentException("주문을 찾을 수 없습니다."));

        return orderDto;
    }

    @Transactional
    public Page<OrderDto> findAll(Pageable pageable){
        return orderRepository.findAll(pageable) //pageable 객체를 이용하면 손쉽 page 쿼리를 보낼 수 있다.
                .map(orderConverter::convertOrderDto);
    }
}

 

 

page 객체

 

Controller layer

공통 응답 폼

@Getter
@Setter
@NoArgsConstructor
public class ApiResponse<T> {
    private int statusCode;
    private T data;
    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyy-MM-dd HH:mm:ss", timezone = "Asia/Seoul")
    private LocalDateTime serverDataTime;

    public ApiResponse(int statusCode, T data) {
        this.statusCode = statusCode;
        this.data = data;
        this.serverDataTime = LocalDateTime.now();
    }

    public static <T> ApiResponse<T> ok(T data){
        return new ApiResponse<>(200,data);
    }

    public static <T> ApiResponse<T> fail(int statusCode,T data){
        return new ApiResponse<>(statusCode,data);
    }
}

OrderController.class

@RestController
public class OrderController {

    @Autowired
    private OrderService orderService;

    @ExceptionHandler(NotFoundException.class) // 공통 예외처리
    public ApiResponse<String> notFoundHandler(NotFoundException e) {
        return ApiResponse.fail(404, e.getMessage());
    }

    @ExceptionHandler(Exception.class)
    public ApiResponse<String> internalServerErrorHandler(NotFoundException e) {
        return ApiResponse.fail(500, e.getMessage());
    }

    @PostMapping("/orders")
    public ApiResponse<String> save(@RequestBody OrderDto orderDto) {
        String uuid = orderService.save(orderDto);
        return ApiResponse.ok(uuid);
    }

    @GetMapping("/orders/{uuid}")
    public ApiResponse<OrderDto> getOne(@PathVariable String uuid) throws NotFoundException {
        OrderDto orderDto = orderService.findOne(uuid);
        return ApiResponse.ok(orderDto);
    }

    @GetMapping("/orders")
    public ApiResponse<Page<OrderDto>> getAll(Pageable pageable){
        Page<OrderDto> all = orderService.findAll(pageable);
        return ApiResponse.ok(all);
    }
}

 

controller test

어플리케이션을 띄우지않고 테스트 코드로 확인

package com.example.kdtspringjpa.order.controller; 
...
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@AutoConfigureMockMvc
@SpringBootTest
class OrderControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private OrderService orderService;

    @Autowired
    private ObjectMapper objectMapper;

    @Test
    void saveCallTest() throws Exception {
        // When
        OrderDto orderDto = OrderDto.builder()
                .uuid(UUID.randomUUID().toString())
                .memo("문앞 보관 해주세요.")
                .orderDatetime(LocalDateTime.now())
                .orderStatus(OrderStatus.OPENED)
                .memberDto(
                        MemberDto.builder()
                                .name("장영지")
                                .nickName("young")
                                .address("영지네 집")
                                .age(28)
                                .description("---")
                                .build()
                )
                .orderItemDtos(List.of(
                        OrderItemDto.builder()
                                .price(1000)
                                .quantity(100)
                                .itemDtos(List.of(
                                        ItemDto.builder()
                                                .type(ItemType.FOOD)
                                                .chef("백종원")
                                                .price(1000)
                                                .build()
                                ))
                                .build()
                ))
                .build();

        // When // Then
        mockMvc.perform(post("/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(orderDto)))
                .andExpect(status().isOk())
                .andDo(print());

    }

		@Test
    void getAll() throws Exception {
        mockMvc.perform(get("/orders")
                        .param("page", String.valueOf(0))
                        .param("size",String.valueOf(10))
                        .contentType(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andDo(print());
    }
}

 

• 응답 한글이 깨질 경우 : yaml에 server encoding 추가

server:
  servlet:
    encoding:
      charset: UTF-8
      enabled: true
      force: true

---

 

API 문서화 - RestDocs

mockmvc를 이용해서 test code 기반으로 API 문서 만들기

@Test
void saveCallTest() throws Exception {
  // When
  OrderDto orderDto = OrderDto.builder()
          .uuid(UUID.randomUUID().toString())
          .memo("문앞 보관 해주세요.")
          .orderDatetime(LocalDateTime.now())
          .orderStatus(OrderStatus.OPENED)
          .memberDto(
                  MemberDto.builder()
                          .name("장영지")
                          .nickName("young")
                          .address("영지네 집")
                          .age(28)
                          .description("---")
                          .build()
          )
          .orderItemDtos(List.of(
                  OrderItemDto.builder()
                          .price(1000)
                          .quantity(100)
                          .itemDtos(List.of(
                                  ItemDto.builder()
                                          .type(ItemType.FOOD)
                                          .chef("백종원")
                                          .price(1000)
                                          .build()
                          ))
                          .build()
          ))
          .build();

  // When // Then
  mockMvc.perform(post("/orders")
                  .contentType(MediaType.APPLICATION_JSON)
                  .content(objectMapper.writeValueAsString(orderDto)))
          .andExpect(status().isOk())
          .andDo(print())
          .andDo(document("order-save", // 파일명
                  requestFields(
                          fieldWithPath("uuid").type(JsonFieldType.STRING).description("UUID"),
                          fieldWithPath("orderDatetime").type(JsonFieldType.STRING).description("orderDatetime"),
                          fieldWithPath("orderStatus").type(JsonFieldType.STRING).description("orderStatus"),
                          fieldWithPath("memo").type(JsonFieldType.STRING).description("memo"),
                          fieldWithPath("memberDto").type(JsonFieldType.OBJECT).description("memberDto"),
                          fieldWithPath("memberDto.id").type(JsonFieldType.NULL).description("memberDto.id"),
                          fieldWithPath("memberDto.name").type(JsonFieldType.STRING).description("memberDto.name"),
                          fieldWithPath("memberDto.nickName").type(JsonFieldType.STRING).description("memberDto.nickName"),
                          fieldWithPath("memberDto.age").type(JsonFieldType.NUMBER).description("memberDto.age"),
                          fieldWithPath("memberDto.address").type(JsonFieldType.STRING).description("memberDto.address"),
                          fieldWithPath("memberDto.description").type(JsonFieldType.STRING).description("memberDto.desc"),
                          fieldWithPath("orderItemDtos[]").type(JsonFieldType.ARRAY).description("memberDto.desc"),
                          fieldWithPath("orderItemDtos[].id").type(JsonFieldType.NULL).description("orderItemDtos.id"),
                          fieldWithPath("orderItemDtos[].price").type(JsonFieldType.NUMBER).description("orderItemDtos.price"),
                          fieldWithPath("orderItemDtos[].quantity").type(JsonFieldType.NUMBER).description("orderItemDtos.quantity"),
                          fieldWithPath("orderItemDtos[].itemDtos[]").type(JsonFieldType.ARRAY).description("orderItemDtos.itemDtos"),
                          fieldWithPath("orderItemDtos[].itemDtos[].price").type(JsonFieldType.NUMBER).description("orderItemDtos.itemDtos"),
                          fieldWithPath("orderItemDtos[].itemDtos[].stockQuantity").type(JsonFieldType.NUMBER).description("orderItemDtos.itemDtos"),
                          fieldWithPath("orderItemDtos[].itemDtos[].type").type(JsonFieldType.STRING).description("orderItemDtos.itemDtos"),
                          fieldWithPath("orderItemDtos[].itemDtos[].chef").type(JsonFieldType.STRING).description("orderItemDtos.itemDtos")
                  ),
                  responseFields(
                          fieldWithPath("statusCode").type(JsonFieldType.NUMBER).description("상태코드"),
                          fieldWithPath("data").type(JsonFieldType.STRING).description("데이터"),
                          fieldWithPath("serverDataTime").type(JsonFieldType.STRING).description("응답시간")
                  )
          ));

}

 

• 문서와 API가 일치하지않을때 오류를 띄워줘 문서의 최신화를 유지할 수 있다는 장점이 있다. (스펙과 일치하는지)

target > generated-snippets 폴더에 문서가 생성된 것을 확인 가능.

 

 

가독성이 떨어지는 문서를 확인할수있다.

➕

상단 가이드에 따라 intelliJ 플러그인을 설치하면 훨씬 보기 좋아진다!

 

 

IntelliJ의 도움 없이 플러그인을 추가하여 파일을 만들어보자.

1. 플러그인 추가

<plugin>
    <!-- for Spring REST Docs -->
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.0.0</version>
    <executions>
        <execution>
            <id>generate-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html</backend>
                <doctype>book</doctype>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-asciidoctor</artifactId>
            <version>${spring-restdocs.version}</version>
        </dependency>
    </dependencies>
</plugin>

 

2. index.adoc 파일을 통해 원하는 폼을 만들 수 있다.

:hardbreaks:
ifndef::snippets[]
:snippets: ../../../target/generated-snippets
endif::[]

 

3. 플러그인 실행

target > generated-docs 폴더에 html 문서가 생성된 것을 확인 할수있다.

 

 

 

 

API 문서화 - Swagger

단점 : 운영 코드상에 docment 화를 하기위한 문서 어노텡이션이 추가된다.

→ 유지보수가 힘들다. 테스트 코드를 진행하지 않고 문서화를 하다보니 검증이 재대로 되지않은 문서가 생성될 수 있다.

예시 코드

 

 

 

 

 

출처 - backend dev course 강홍구님