[SpringBoot] 협업을 위한 Swagger 사용법

Swagger 사용기

안녕하세용 오늘은 프론트와 백이 협업을 하며 사용하면 좋은 Swagger에 대한 사용법을 알아보도록 하겠습니다.🙂

 

Swagger를 처음 접하시는 분들께 설명드리자면 Swagger는 OpenAPI 명세(OpenAPI Specification, OAS)의 핵심 도구 중 하나입니다. OpenAPI는 RESTful API를 위한 API 설계에 대한 표준 언어 및 프로세스를 정의합니다. 이 명세는 API의 모든 측면을 기술적으로 설명하여 API의 기능을 정확히 이해하고 올바르게 사용할 수 있게 합니다.

 

본 프로젝트는 Java 17 , SpringBoot 3.2.2 , gradle 8.5 버전을 사용합니다.

 

 

의존성 추가

아래의 의존성을 사용해 줍니다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

아래는 예전 버전의 의존성인데 추가하니 Gradle에서 오류를 발생시키네요..

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

// 오류
> Task :BookEverywhereApplication.main() FAILED

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

혹시나 같은 오류가 있으신 분들은 첫 번째 의존성을 추가하시기 바랍니다~

 

 

SwaggerConfig 설정 및 예시

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("springdoc-public")
                .pathsToMatch("/**")
                .build();
    }

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Book Everywhere API")
                        .version("v1")
                        .description("읽는곳곳 API 명세서"));
    }
}

• GroupedOpenApi 빈을 통해 API를 그룹화하고, 어떤 경로(pathsToMatch("/**"))가 문서화될지 지정합니다. 여기서는 모든 경로를 문서화하도록 설정했습니다.
• OpenAPI 빈을 사용하여 API 문서의 정보(제목, 버전, 설명)를 커스터마이징 합니다.

❗ ❗ 이후에 아래 링크를 통해 들어가시면 보이게 됩니다. 혹시나 CICD 설정으로 HealthChecking을 위하여@RequestMapping("/**") 같은 어노테이션이 붙어있는 컨트롤러가 있다면 정상적인 동작을 하지 않을 수 있습니다.

http://localhost:{로컬포트번호 ex:8080}/swagger-ui/index.html#/

✅Controller에 예시로 추가적인 옵션을 붙여보도록 하겠습니다.

@RestController
@RequiredArgsConstructor
public class ReviewController {


    private final PinService pinService;
    private final TagService tagService;
    private final VisitService visitService;
    private final BookService bookService;
    private final ReviewService reviewService;

    @PostMapping("/api/write")
    @Operation(summary = "독후감 추가", description = "독후감을 새로 추가합니다.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "독후감 추가 완료", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = CMRespDto.class))}), 
            @ApiResponse(responseCode = "400", description = "잘못된 요청", content = @Content),
            @ApiResponse(responseCode = "500", description = "서버 에러", content = @Content)
    })
    public CMRespDto<?> addReview(@RequestBody ReviewRespDto reviewRespDto) {
        pinService.핀생성(reviewRespDto);
        bookService.책생성하기(reviewRespDto);
        tagService.태그등록(reviewRespDto);
        visitService.독후감쓰기전방문등록(reviewRespDto);
        reviewService.독후감생성하기(reviewRespDto);
        return new CMRespDto<>(HttpStatus.OK, null, "독후감 추가 완료");
    }

}

✅ Operation애너테이션을 사용하여 API의 요약과 설명을 추가해 봤습니다.@ApiResponses애너테이션은 가능한 HTTP 응답 상태 코드와 그에 대한 설명, 그리고 응답 본문의 구조를 알려줍니다.

적용했을때의 swagger ui입니다.

✅ Front 팀원들이 이해하기 쉽게 잘 나타나져서 앞으로 유용하게 사용될 것 같습니다.

 

감사합니다!😊

 

+++ 추가  / HTTPS 설정

✅ Swagger Servers는 기본적으로 http를 지원합니다. 그렇기 때문에 https로 설정되어있는 저희의 홈페이지에 Request를 보내니 정상 작동을 하지 않았는데요, 그래서 HTTPS 설정하는 방법을 추가합니다!

 

✅ 방법은 아주 간단합니다.

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .addServersItem(new Server().url("https://api.bookeverywhere.site").description("Generated server url"))
                .info(new Info()
                        .title("Book Everywhere API")
                        .version("v1")
                        .description("읽는곳곳 API 명세서"));
    }
}

 

✅.addServersItem 줄을 추가해주시면 됩니다! 

 

잘 해결되어 data가 잘 보이네요 😋

 

감사합니다!