Swagger

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

 

Spring Boot 프로젝트에서 Swagger-UI를 통해 개발한 Rest API 들의 목록을 확인하고 테스트 할 수있다.

 

Swagger

- 개발한 Rest API를 문서화 한다.
- API 호출을 통한 테스트를 가능하게 한다. 

=> api 단위테스트, 명세서 다 가능하다

---

< Swagger 설정 & 프로젝트 적용 >

 

build.gradle 의존성 추가    swagger 라이브러리 추가

implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.2.0'

---

< Swagger UI가 API 문서를 제공하는 경로 설정 >

 

application.properties

#-------------------------------------------------
# Swagger 설정
#-------------------------------------------------
# API 문서의 기본 경로 설정 (/api-docs로 API 문서 제공)
springdoc.swagger-ui.path=/api-docs

---

< 설정 파일 추가 >

 

SwaggerConfig.java

package com.hyeon.account;

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

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

@Configuration
public class SwaggerConfig {
    
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())   // Swagger 구성 요소 설정
                .info(apiInfo());               // API 정보 설정
    }

    private Info apiInfo() {
        return new Info().title("Account Swagger")          // API 문서 제목
                        .description("Account REST API")    // API 문서 설명
                        .version("1.0.0");                  // API 문서 버전
    }
}

---

< Controller 적용 >

 

@Tag 추가

@RestController
@Tag(name="Account API", description="가입, 로그인, 정보수정, 탈퇴 등 회원 관련 API")
public class AccountRestController {

 

@Operation,  @ApiResponses,  @Parameters  추가

@GetMapping("/api/account/id_unique_check")
@Operation(summary = "아이디 중복 검사", description = "파라미터로 받은 아이디의 중복 여부를 검사한다.")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "사용 가능한 아이디 입니다.", 
                content = @Content(mediaType = "application/json", 
                schema = @Schema(implementation = Map.class))),
    @ApiResponse(responseCode = "400", description = "이미 사용중인 아이디 입니다.", 
                content = @Content(mediaType = "application/json", 
                schema = @Schema(implementation = Map.class)))
})
@Parameters({
    @Parameter(name = "user_id", description = "검사할 아이디", schema = @Schema(type = "string"), required = true)
})
public Map<String,Object> idUniqueCheck(@RequestParam("user_id") String userId) {
    try {
        memberService.isUniqueUserId(userId);
    } catch (Exception e) {
        return restHelper.badRequest(e);
    }

    return restHelper.sendJson();
}

 

@Operation

API 엔드포인트의 설명을 설정한다.

 

@ApiResponses

API 엔드포인트의 가능한 응답을 정의한다.

 

@Parameters

API 엔드포인트의 파라미터를 정의한다.

---

⬇️  localhost:8080/api-docs  

 

 

 

 

---

refer to

https://lucas-owner.tistory.com/28