[스프링부트] Swagger 연동하기

갑자기 Swagger 를 사용해야되는 상황이 와버렸다. 😨
처음 듣는 용어.. 너.. 되게 낯설다.. 😱
그래서 오늘은 Swagger에 대해서 간단하게 살펴보자.

Swagger

Swagger는 개발한 REST API 를 편리하게 문서화 해주고, 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트다.
단, 운영환경과 같은 외부에 노출되면 안되는 곳에 사용할 때는 주의하자.

다행히 Spring Boot 에서는 간단하게 springfox-boot-starter를 gradle dependecies에 추가하면 사용할 수 있다. 😤

자세한건 공식 홈페이지 에서 확인해보자.

Swagger Annotation

Annotation	Desc
@Api	클래스를 스웨거의 리소스로 표시
@ApiOperation	특정 경로의 오퍼레이션 HTTP 메서드 설명
@ApiParam	오퍼레이션 파라미터에 메타데이터 설명
@ApiResponse	오퍼레이션의 응답 지정
@ApiModelProperty	모델의 속성 데이터를 설명
@ApiImplicitParam	메서드 단위의 오퍼레이션 파라미터를 설명

프로젝트 생성

프로젝트 생성은 여기서 가능하다.

Project: Gradle Project
Language: java
Spring Boot: 2.5.4
Group: com.example
Artifact: swagger
Packaging: Jar
Java: 11
Dependencies: Lombok, Spring web

Swagger Dependency는 여기에 없으므로 Maven Repository에서 다운받도록 하자.

Swagger Dependency

Swagger를 받을 수 있는 곳은 여기이고 나온지 얼마 되지 않아서 버전은 3.0.0 딱 하나 존재한다. 기존에는 Springfox Swagger2, Springfox Swagger UI 두개를 사용했지만 최근에는 Springfox-boot-starter가 나와서 하나만 의존성을 추가해도된다.

// https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

Swagger를 사용하기 위해 build.gradle에 있는 dependencies 부분에 위 내용을 추가하자. (아래 그림처럼 작성하면 된다. 참 쉽죠잉?)

실행

controller 패키지를 생성하고 하위에 ApiController 클래스를 추가하였고, 클래스 내용은 아래와 같이 작성했다.

@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }
}

두근두근!!😳 그럼 서버를 구동하고 http://localhost:8080/swagger-ui/ 뙇!

swagger-ui 뒤에 꼭 /를 붙여줘야한다. 안 붙이면 404 NOT FOUND..😫

간지나는(?) 화면에 우리가 작성한 컨트롤러가 보인다.
basic-error-controller는 스프링에서 자동으로 설정된 컨트롤러이다. api-controller를 눌러서Try it out 버튼을 클릭하고, Execute 버튼을 클릭하면 서버 응답값인 hello를 확인할 수 있다.

간단하게 Swagger를 알아보고 프로젝트를 생성해서 확인해봤다. 하지만 이렇게 쓰기에는 좀... 🙄
다음 시간에 Swagger를 더 설정해보고 알아보도록 하자.