[SPRING BOOT] SWAGGER2 사용하여 api 테스터 만들기 postman 보다 편리한 swagger2

 

오늘은 post man 대신 swagger2 를 사용해보겠다.

 

일단 swagger 에대해 알아보자

 

 

swagger 란?

위키백과에 있는스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.

 

일단 swagger 는 api 문서를 자동으로 작성해주는 라이브러리이다.

개발자들이 따로 작성할 필요없이 spring boot와 연동하여

controller가 어디있고 어떤 매게변수를 받고 어떤것을 리턴해주는지 전부 자동으로 해주는

매우 편리한 도구이다

또한 postman 에서 일일이 url을 작성하여 요청하는 이런 귀찮음을 피할수도있는 매우 유용한 도구이다.

 

다만 단점은 설정이 생각보다 까다롭다는것이다.

까다롭다는건 버전과 바뀐 규칙들이 생각보다 많기때문에 정확한 정보를 찾기가 어렵다.

 

다행히 삽질은 내가하니 여러분은 보고 따라하기만 하면된다.

하지만 나와 버전이 다른사람은 동작을 안할수도있으니 버전을 참고하기바란다.

 

 

 

 

 

폴더 구조

 

 

 

 

 

 

# 0 . 디펜던시 설정과 스프링부트 버전

 

이부분에 대해 말이 엄청많다 누구는 2.9.2 버전을 쓰고 누구는 2.7 버전을 쓰고 누구는 3.0 을 써야 오류가 안난다...등등

 

확실한건 

 

나는 스프링 부트 2.7.7 버전을 사용하고있다

대략적인 스팩을 밑에 적겠다

 

아래 build.gradle 파일이 있으니 참고바란다.

 

 

 

 

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '2.7.7'   // < ------- 스프링 부트 버전
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11' // <------- java 11
application.yml

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.springfox:springfox-boot-starter:3.0.0") // <--------- spring boot starter
    implementation("io.springfox:springfox-swagger-ui:3.0.0") // <--------- 스웨거 ui
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springframework.boot:spring-boot-starter-aop'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    runtimeOnly 'com.mysql:mysql-connector-j'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

 

 

 

 

 

# 1 . application.yml 설정 

 

application.yml

spring:
  mvc:
    pathmatch:
      matching-strategy: path_pattern_parser

 

다른 글들에 ant_path_matcher 로 해야한다는 사람도 있지만 나와 같은 버전이라면 path_pattren_parser 가 맞다

다른 버전이라도 오류가 난다면 나처럼 해보길 바란다.

 

 

 

# 2 . config 설정  << 메인 작업

 

SwaggerConfiguration.java

package com.example.backend.config;

import org.springframework.beans.factory.annotation.Configurable;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.web.config.EnableSpringDataWebSupport;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableAsync
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfiguration implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.backend.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo () {
        return new ApiInfoBuilder()
                .title("ig Clone API")
                .description("인스타그램 클론코딩 api")
                .version("1.0")
                .build();
    }
}

메인작업이다.

 

대략 설명하자면

api() 는 어떤 컨트롤러를 사용할것이고 어떤 path만 등록을 할건지 커스텀 하는부분이고

 

apiInfo() 또한 swagger2 접속시 보여주는 내용들을 정의하는것이다 한마디로 java api 에 author 생각하면 쉬울것이다.

 

 

 

 

 

 

 

# 3 . 컨트롤러 생성

 

UserController.java

package com.example.backend.controller;

import com.example.backend.common.exception.CustomApiException;
import com.example.backend.dto.CMRespDto;
import com.example.backend.dto.user.request.RequestUserRegisterDto;
import com.example.backend.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;

@RestController
@RequiredArgsConstructor
@CrossOrigin(origins = {"*"})
@RequestMapping("/api/user")
public class UserController {

    private final UserService userService;
    @PostMapping("/register")
    public CMRespDto<?> register (@Valid @RequestBody RequestUserRegisterDto requestUserRegisterDto) {
        System.out.println("123");
        return new CMRespDto<>(200, "정상처리", null);
    }

    @GetMapping("/hi")
    public CMRespDto<?> hi (){
        userService.register();
        return new CMRespDto<>(200, "정상처리", null);
    }
}

 

상단에 만든 configurtion 을 바탕으로 이 컨트롤러가 등록이될것이다.

 

이제 서버재시작을 누르고 swagger에 접속해보자

 

 

 

# 주의 해야할점

swagger 에 접속했을때 자신의 spring boot port가 8080 이라면

http://localhost:8080/swagger-ui/index.html

이렇게 접속하면 접속이 안될수도있다

 

안된다면 

꼭!!!!

 

http://localhost:8080/swagger-ui/index.html#/

 

뒤에 /#/을 붙여서 접속하자

 

 

 

 

 

 

정상적으로 동작하는걸 볼수있다.

 

try in out을 누른후 excute 를 누르면 post man 처럼 api 요청이 가는걸 볼수있다.

 

 

 

보이는 에러는 예외처리 테스트 하느라 보이는거니 신경안써도된다.

 

 

이것으로 swagger 를 이용한 api 문서만들기를 마치도록하겠다.