20230209 Ajax & Swagger API

Ajax (에이젝스, 아젝스, 아약스)

Ajax(Asynchronous Javascript and Xml)는 비동기적 자바스크립트와 xml.
비동기적이란, 서버에 요청이 들어온 후 프로그램은 멈추지 않고 계속 돌아간다는 의미이고, XML은 데이터 형식의 종류이다. Ajax를 통해 주로 주고 받는 형태가 XML이나 JSON 형태의 파일이다.

http 프로토콜은 기본적으로 클라이언트 쪽에서 request를 보내고 server의 response를 받으면 연결이 끊어진다. 화면의 내용을 갱신하기 위해서는 다시 request를 하고 페이지 전체의 내용을 다시 response로 받게 된다.
일부 페이지를 업데이트 하고 싶다면, Ajax가 효율적이다.
Ajax는 XMLHttpRequset 객체를 통해서 request를 보낸다.
Javascript를 통해 Ajax를 사용한다.

Swagger

spring 3version과 2version에 사용하는 것이 다름 -> 오늘은 spring 3 version으로 진행한다.

사용전, gradle에 아래 내용추가해 주어야함
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.0' implementation 'org.springframework.boot:spring-boot-starter-validation'
저장시 안내가 뜸 -> always 체크

application.properties에 아래 괄호안의 내용 추가
(# Swagger Settings
springdoc.default-consumes-media-type=application/json
springdoc.default-produces-media-type=application/json
springdoc.api-docs.groups.enabled=true
springdoc.swagger-ui.operations-sorter=alpha
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.path=/swagger
springdoc.swagger-ui.disable-swagger-default-url=true
springdoc.swagger-ui.doc-expansion=none
springdoc.paths-to-match=/api/**)

yaml 파일의 경우, 아래처럼 입력

# Swagger Settings 
springdoc:
  # 요청 데이터 형태
  default-consumes-media-type: application/json
  # 응답 데이터 형태
  default-produces-media-type: application/json
  api-docs:
    groups:
      # API문서 그룹화 여부
      enabled: true
  swagger-ui:
    # 정렬 기준 (알페벳 기준) 
    operations-sorter: alpha
    tags-sorter: alpha
    # swagger 접근 기본 경로
    path: /swagger
    # 기본 경로 설정 비활성화 여부
    disable-swagger-default-url: true
    # 문서 확장기능 사용 여부
    doc-expansion: none
  paths-to-match:
    # 문서로 만들 API요청 경로 목록 (요청 경로가 /api/로 시작하면 모두 문서화)
    - /api/**

config 폴더에 파일 작성

package com.greenart.flo_service.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;

@Configuration
public class SwaggerConfig {
  @Bean
  public OpenAPI floOpenAPI() {
    // version, title, description은 마음대로 설정
    Info info = new Info().version("0.0.1").title("FLO서비스 API").description("FLO서비스 Restful API 명세서");
    return new OpenAPI().info(info);
  }
}

주소창에 http://localhost:서버/swagger를 입력한다.

위와 같이 각 기능에 관련된 api명세서가 자동으로 작성된다.

parameter나 result에 대해서도 자동으로 출력된다.

아무 설정을 하지 않는다면 api controller기준으로 grouping이 됨.

controller 별 상세설정

@restcontroller 위에 tag annotation을 통해 controller의 이름과 설명을 추가 할 수 있음.

@Tag(name = "곡 장르 정보 관리", description="장르 정보 CRUD API")

각각의 매핑위에 operation annotation을 통해 mapping별 이름과 설명을 추가 할 수 있음.

 @Operation(summary="장르 리스트", description="등록된 장르정보를 10개 단위로 보여줍니다.")

각각의 parameter 앞에 parameter annotation을 통해 parameter별 설명을 추가 할 수 있음. example을 통해 예시를 보여줄 수도 있음.

public ResponseEntity<Object> getGenreList(@Parameter(description = "검색어",example="JYP") @RequestParam @Nullable String keyword,
      @PageableDefault(size = 10, sort = "genreSeq", direction = Direction.DESC) Pageable pageable)

@PageableAsQueryParam : pageable을 parameter로 받음
@Parameter(hidden = true) : parameter를 숨김

@Operation(summary = "장르 리스트", description = "등록된 장르정보를 10개 단위로 보여줍니다.")
  // pageable을 parameter로 받음
  @PageableAsQueryParam
  @GetMapping("/list")
  public ResponseEntity<Object> getGenreList(@Parameter(description = "검색어",example="JYP") @RequestParam @Nullable String keyword,
      // @Parameter(description = "페이징 처리, URL 파라미터로 요청 예시) /api/genre/list?page=0") 
      @Parameter(hidden = true) @PageableDefault(size = 10, sort = "genreSeq", direction = Direction.DESC) Pageable pageable) {
    if (keyword == null) {
      keyword = "";
    }
    // model.addAttribute("result", gService.getGenreList(keyword, pageable));
    // model.addAttribute("keyword", keyword);
    return new ResponseEntity<>(gService.getGenreList(keyword, pageable), HttpStatus.OK);
  }

아래처럼 페이지 사이즈를 파라미터 값을 입력할 수 있게 설정됨.

VO와 Entity에서는 schema annotation을 통해 설명가능.

package com.greenart.flo_service.vo;
import java.util.List;
import com.greenart.flo_service.entity.GenreEntity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Builder;
import lombok.Data;

@Data
@Builder
public class GenreListResponseVO {
  @Schema(description = "장르 리스트")
  private List<GenreEntity> list;
  @Schema(description = "총 장르 수", example = "121")
  private Long total;
  @Schema(description = "총 페이지 수", example = "13")
  private Integer totalPage;
  @Schema(description = "조회한 페이지 (1페이지 -> 0 / 2페이지 ->1", example = "0")
  private Integer currentPage;
}

response에서 schema를 클릭하면,

위와 같이 설명을 볼 수 있음.