스프링 부트 Swagger 설정하고 사용해보기

Swagger 설정에 앞서 Swagger가 뭔지 알아보겠습니다.

Swagger란 OAS(Open Api Specification)을 위한 오픈소스 프레임워크이다.
   - API 개발 과정에서 변경이 있으면 그에 따른 명세(Spec)도 변경이 있을 것이다.
     이러한 작업은 번거롭고 시간 또한 오래 걸린다.
     이 같은 문제를 해결하기 위한 것이 바로 Swagger라는 프로젝트이다.
     (API가 수정돼도 자동으로 문서가 갱신된다.)

What is the OpenAPI Specification?

 

The OpenAPI Specification, formerly known as the Swagger Specification, is the world’s standard for defining RESTful interfaces. The OAS enables developers to design a technology-agnostic API interface that forms the basis of their API development and consumption.

이전에 Swagger 사양으로 알려졌던 OpenAPI 사양은 RESTful 인터페이스를 정의하기 위한 세계 표준입니다. OAS를 통해
개발자는 API 개발 및 소비의 기반을 형성하는 기술에 구애받지 않는 API 인터페이스를 설계할 수 있습니다.

https://swagger.io/solutions/getting-started-with-oas/

그럼 이제, Swagger을 설정하고 간단하게 사용해보겠습니다.
우선 Swagger을 사용하기 위해서 pom.xml 파일에 Swagger 의존성을 추가합니다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>


<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

이어서  Swagger와 관련된 설정 코드를 작성해보겠습니다.      

SwaggerConfiguration(설정 클래스)

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

     @Bean
     public Docket api(){
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo()) //제목,설명 등 문서에 대한 정보들
                 .select() //ApiSelectorBuilder 생성
                 .apis(RequestHandlerSelectors.basePackage("com.example.api")) //Swagger에서 스캔할 패키지 범위를 지정
                 .paths(PathSelectors.any()) // apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링 - PathSelectors.any() -> always true
                 .build();
     }

     private ApiInfo apiInfo(){
         return new ApiInfoBuilder()
                 .title("스프링 부트 Swagger 사용해보기!")
                 .description("Swagger 설명!")
                 .version("1.0.0")
                 .build();
     }

}

기본적인 Swagger 사용을 위한 설정은 끝났습니다.

간단한 API를 만들어서 Swagger을 사용해 보겠습니다.

GetController

@RestController
@RequestMapping("/api/v1")
@Api(tags = {"get api example"})
public class GetController {

    @ApiOperation(value = "GET 메서드 예제" , notes = "User GET Method")
    @GetMapping(value = "/users")
    public UserDto getRequestParam(@ModelAttribute UserDto userDto){
        return userDto;
    }

}

UserDto

@Data
public class UserDto{

    @ApiParam(value = "이름", required = true)
    private String name;

    @ApiParam(value = "이메일", required = true)
    private String email;

    @ApiParam(value = "회사", required = false)
    private String organization;
}

 

어노테이션	설명
@Api	클래스를 Swagger 리소스로 표시하기 위한 어노테이션
@ApiOperation	대상 API의 설명을 작성하기 위한 어노테이션
@ApiParam	매개변수에 대한 설명 및 설정을 위한 어노테이션

 

간단한 작업이 끝나면, 이제 http://localhost:8080/swagger-ui.html 로 접속해보겠습니다.

swagger-ui.html

보시다시피, @ApiOperation에 작성한 내용은 그림 상단에 표기되고,   @ApiParam에 정의한 내용은 아래 'Parameters' 안에 설명되어있습니다.
위 그림처럼 Swagger는 해당 Api가 무엇인지 설명해줍니다.

심지어 직접 통신도 시도할 수 있습니다.
위 버튼 중 [Try it out] 버튼을 클릭하고  Parameter 정보들을 입력 후 Exceute 버튼을 누르면 다음과 같은 화면이 표시됩니다.

Swagger를 통한 통신 결과

 

지금까지 간단하게 API를 만들고 Swagger을 사용해보았습니다. 감사합니다.

 

참고:   https://wikibook.co.kr/springboot/
           https://victorydntmd.tistory.com/341