[Swagger] 스웨거 사용법 (Spring Boot)

Swagger

- Swagger는 API 문서화와 API 개발을 지원하기 위한 오픈 소스 프레임워크이다. Swagger를 사용하면 API를 쉽게 문서화하고 시각적으로 표현할 수 있으며, 클라이언트 개발자들이 API를 쉽게 이해하고 테스트할 수 있다.

 

주요 기능

• API 문서화 :  API 엔드포인트, 매개변수, 요청 및 응답 형식, 인증 등 API에 대한 자세한 문서를 작성할 수 있다.
• 자동화된 문서 생성 :  소스 코드에 주석을 추가하여 API에 대한 문서를 자동으로 생성할 수 있다. 이를 통해 개발자는 API 변경 시 문서를 일일이 업데이트할 필요 없이 최신 정보를 유지할 수 있다.
• 시각화된 API UI :  Swagger UI를 통해 API를 시각적으로 표현한다. Swagger UI는 사용자가 API를 쉽게 테스트하고 결과를 확인할 수 있는 인터페이스를 제공한다. 개발자들은 Swagger UI를 통해 API 엔드포인트를 호출하고 요청 및 응답을 확인할 수 있다.
• API 테스트 :  Swagger UI를 통해 사용자는 API를 직접 테스트할 수 있다. API에 대한 입력 필드를 제공하고, 사용자가 필요한 매개변수를 설정하고 요청을 보낼 수 있다. 그리고 응답 결과를 확인할 수 있다.
• 클라이언트 코드 생성 :  API 정의를 기반으로 클라이언트 코드를 자동으로 생성할 수 있다. 이를 통해 클라이언트 개발자는 API를 더 쉽게 호출하고 사용할 수 있다.

 

평소 Postman을 주로 사용해왔지만, 이번 팀 프로젝트에서 팀원들이 swagger를 사용하는 것을 보고 배워보고 싶었다.

 

사용법

1. 의존성 추가 ( build.gradle )

//swager
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
    implementation 'io.springfox:springfox-swagger-ui:3.0.0'

 

2. Docket의 Bean 등록을 위한 클래스 생성 ( SwaggerConfig.java)

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .securityContexts(Collections.singletonList(securityContext()))
                .securitySchemes(List.of(apiKey()))
                .select()
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo());
    }

    //이후 권한인증 확인을 위해서
    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .build();
    }

    //이후 권한인증 확인을 위해서
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return List.of(new SecurityReference("Authorization", authorizationScopes));
    }

    private ApiKey apiKey() {
        return new ApiKey("Authorization", "Authorization", "header");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ColdPitch API")
                .description("콜드피치 API 명세")
                .version("1.0.0")
                .build();
    }
}

 

3. 컨트롤러 작성

- 현재 프로젝트의 기능에 포함되는 사업자 등록번호 진위검증 컨트롤러 

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1/company")
public class CompanyRegistrationController {
    private final CompanyRegistrationService companyRegistrationService;

    @PostMapping("/validate")
    @Operation(summary = "사업자 등록번호 진위검증")
    public ResponseEntity<CompanyRegistrationDto> validate(@RequestBody CompanyRegistrationDto companyRegistrationDto, BindingResult result) {
        if (result.hasErrors()) {
            throw new CustomException(ErrorCode.POST_BAD_REQUEST);
        }

        boolean isValid = companyRegistrationService.validateAndSaveCompanyRegistration(companyRegistrationDto);

        if (!isValid) {
            throw new CustomException(ErrorCode.COMPANY_NOT_FOUND);
        }

        return ResponseEntity.ok(companyRegistrationDto);
    }
}

 

4. 테스트

- Try it out 이후, 서버에서 요청하는 데이터를 형식에 맞게 request에 넣은 후 execute

 

5. 결과 확인 

- 간단하게 워크벤치에서 확인해보니 해당 요청을 잘  받아서 무사히 db에 저장된 것을 볼 수 있다.