[Spring Boot] Swagger 사용하기

개요

---

프론트엔드와 백엔드간 협업을 하기 위해 백엔드에서 구축한 API 스펙을 문서화 하여 프론트엔드에게 보여줘야한다.이때 API 문서를 효과적으로 만들기 위해 사용할 수 있는 라이브러리를 찾아 보았고, swagger 라는 라이브러리를 알게 되었다.

 

 

 

 

Swagger 란?

---

- Swagger는 API를 문서화하고 테스트할 수 있는 오픈 소스 프레임워크이다.

 

- 어노테이션을 통해 간편하게 API 문서를 자동으로 만들 수 있다.

 

- 자체적으로 사용자 친화적인 UI도 제공해주고 있기 때문에 문서를 쉽게 읽고 테스트할 수 있다.

 

 

문서화에 사용되는 어노테이션이 프로덕션 코드에 존재하기에 가독성을 떨어뜨리는 단점도 존재한다. API 스펙이 변했을 때 어노테이션 메타 데이터를 적절하게 바꿔주지 않으면 잘못된 정보를 전달할 수도 있다. 하지만 간편한 설정과 사용, 사용자 친화적인 UI는 큰 장점으로 다가온다.

 

 

Swagger 적용하기

---

Swagger 를 설정하기 위해 2가지의 라이브러리가 존재합니다.

 

- SpringFox

- SpringDoc 

 

SpringFox 는 더이상 업데이트를 해주지 않기 때문에 Spring Boot 특정 버전에서 제대로 동작하지 않는 문제있습니다..

 

따라서 현재 꾸준히 업데이트 해주고 있으며, Spring Boot 최신 버전도 지원하고 있는 SpringDoc 을 사용하겠습니다.

 

 

라이브러리 추가

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

 

설정

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {

        Server server = new Server();   // API 서버 설정
        server.setUrl("/");
        
        Server prodServer = new Server();  // 운영서버에 따로 띄우기 위해 서버를 추가할 수 있다.
        server.setUrl("운영 URL");

        Info info = new Info()
                .title("Swagger API")       // API 문서 제목
                .version("v1.0.0")          // API 문서 버전
                .description("스웨거 API"); // API 문서 설명

        return new OpenAPI()
                .info(info)
                .servers(List.of(server, prodServer));    
    }

}

 

 

 

Swagger 적용 모습

---

 

 

 

SwaggerController

@RestController
@RequestMapping("/api/v1")
public class SwaggerController { 
    // 기본적으로 controller의 이름을 따라갑니다.
    // SwaggerController => swagger-controller 

    @GetMapping("/posts")
    public String getPosts() {
        return "ok";
    }

    @PostMapping("/posts")
    public SwaggerDTO addPosts(SwaggerDTO swaggerDTO) {
        return swaggerDTO;
    }

}

 

 

SwaggerDTO

@Getter
@Setter
public class SwaggerDTO {

    private String name;
    private String phone;

}

 

 

 

 

@

---

 

@Tag 

controller 에 적용

@Tag(name = "스웨거", description = "스웨거 API")
@RestController
@RequestMapping("/api/v1")
public class SwaggerController {

   ...

}

 

 

@Operation: API 엔드 포인트 정의

method 에 적용

@Tag(name = "스웨거", description = "스웨거 API")
@RestController
@RequestMapping("/api/v1")
public class SwaggerController {


    @Operation(summary = "조회", description = "등록된 게시물을 조회합니다.")
    @GetMapping("/posts")
    public String getPosts() {
        return "ok";
    }

   ...

}

 

 

 

@ApiResponse: API 응답에 대한 설명과 상태 코드 정의

method 에 적용

 

@Tag(name = "스웨거", description = "스웨거 API")
@RestController
@RequestMapping("/api/v1")
public class SwaggerController {


    @Operation(summary = "조회", description = "등록된 게시물을 조회합니다.")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "조회 성공"),
            @ApiResponse(responseCode = "400", description = "조회 실패")
    })
    @GetMapping("/posts")
    public String getPosts() {
        return "ok";
    }

   ...
}

 

 

 

 

@Schema: API 모델의 속성 정의

model 에 적용

 

@Getter
@Setter
public class SwaggerDTO {

    @Schema(description = "이름", example = "스웨거")
    private String name;
    private String phone;

}

 

참조

---

https://woo-chang.tistory.com/80