spring/swagger

[swagger] spring 3.x 버전 적용

겸쨔 2024. 7. 21. 23:17
반응형

spring 2.x에서는 swaggerfox를 사용하셨을 거예요.

 

그런데 swaggerfox는 2020년이 마지막 업데이트고,

swaggerdoc은 아마 2023년이 마지막 업데이트일 거예요.

그래서 이 글에서는 springdoc을 가져와서 적용할 거예요.

 

적용 환경은

더보기

JDK 21

Spring 3.2.1

Gradle Kotlin (버전 기억 안 남)

 

의존성은 그레들 기준이에요.

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2")

 

 

저 의존성을 추가하기만 해도 빌드하고 서버 켜보시면 문서로 바로 접근 가능하거든요?

여기서 url은 swaggerfox는 /swagger-ui.html이었는데

swaggerdoc은 /swagger-ui/index.html이에요. 서로 다르죠?

 

swagger 설정은 기본적인 것만 적어볼 거예요.

일단 설정 파일 만들어볼게요.

 

OpenAPI를 반환하는 함수를 bean으로 등록해주시면 돼요.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openApi() {
        return new OpenAPI()
                    .info(new Info()
                            .version("v0.1")
                            .title("프로젝트 이름")
                            .description("API DOC")
                    );
    }

}

 

저장하고 실행하셔서 위 url로 접근하면 바로 나와요.

 

 

여기서부터는 controller, dto 설정인데요.

우리 api 문서를 보고 작업하는 사람들은 프론트쪽 분들이잖아요.

그분들이 보기에 가독성도 좋아야 하고 가시성도 좋아야 하죠.

 

그런데 이 귀찮은 api 문서를 우리가 일일이 또 적어줄 순 없잖아요?

그래서 최대한 재사용해야 하고, 적게 쓰되 많이 보여야 해요.

 

controller나 dto 관련 swagger 설정은 다음 swagger 관련 글에서 작성할게요.

솔직히 @Schema나 @ApiResponses 등을 최적화 하려고 하기엔 까다로운 것 같아서..

좀 더 다듬어보고 최종적으로 제가 다음에 가져다 쓰려고 올리는게 좀 큰 목적으로 작성하는거라

아직은 확정 올리지 않고 더 공부해서 올게요.

 

혹시 이 글 읽으시는 분들 중에 본인이 괜찮게 쓰고 있는 것 같은 분들은 메일이나 따로 댓글 달아주세요.

공유 바랍니다 ㅠㅠ

 

감사합니다.

 

 

반응형