스프링에 swagger 활용하기

swagger란?

Swagger는 API 문서 자동화와 테스트를 위한 오픈 소스 프레임워크입니다. Swagger를 사용하면 API에 대한 문서를 자동으로 생성하고, 테스트할 수 있는 인터랙티브한 UI를 제공합니다.

Swagger의 핵심 구성 요소는 다음과 같습니다:

1. Swagger 문서 (Swagger Specification): API의 구조와 기능을 정의한 JSON 또는 YAML 형식의 문서입니다. Swagger 문서는 API의 엔드포인트, 매개변수, 응답 형식, 인증 등 API에 대한 상세한 정보를 담고 있습니다.
2. Swagger UI: Swagger 문서를 시각적으로 표현하는 사용자 인터페이스입니다. Swagger UI를 통해 API의 엔드포인트를 테스트하고, 요청 및 응답을 확인할 수 있습니다.
3. Swagger Codegen: Swagger 문서를 기반으로 클라이언트 라이브러리나 서버 스켈레톤 코드를 자동으로 생성해주는 도구입니다.

Swagger를 사용하여 API 문서를 작성하고 활용하는 방법은 다음과 같습니다:

1. API 문서 작성: Swagger 문서를 작성하여 API의 엔드포인트, 매개변수, 응답 형식, 인증 등을 정의합니다. Swagger 문서는 JSON 또는 YAML 형식으로 작성됩니다.
2. Swagger UI 적용: Swagger UI를 프로젝트에 적용하여 API 문서를 시각적으로 표현하고, 사용자가 API를 테스트할 수 있는 환경을 제공합니다. Spring Boot에서는 springfox-swagger-ui와 springfox-spring-web 라이브러리를 사용하여 Swagger UI를 적용할 수 있습니다.
3. Swagger Codegen 활용: Swa개발자는 API를 호출하는 클라이언트 코드나 API를 구현하는 서버 코드를 빠르게 생성할 수 있습니다.

Swagger를 사용하면 API 문서의 관리 및 업데이트가 용이해지고, API의 사용법을 명확하게 전달할 수 있습니다. 또한 Swagger UI를 통해 개발자와 협업자들이 API를 테스트하고 문제를 신속하게 파악할 수 있습니다.

 

 

나는 이런게 있는지도 몰랐는데 커피챗에서 알게됨... 다들 이런 도구는 어디서 알고 활용하는거야...

현직자 분께서도 꽤 중요하다고 하셨다... 왜 나만 몰랐냐고 짜증나!!!!!!

 

 

 

---

실전 활용편

 

구글링 해보니까 버전 문제로 골머리 앓은 사람들이 많은 것 같다 버전체크 잘 하기!!!!

내가 swagger를 적용할 프로젝트는 스프링부트 2.7.4 gradle

이에 따라 swagger2를 사용해야 한다.

plugins {
   id 'org.springframework.boot' version '2.7.4'

 

 

build.gradle에 코드 추가하기

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

 

 

Swagger 설정을 위한 SwaggerConfig 클래스 생성

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.yourpackage")) // API 컨트롤러 패키지 경로 설정
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Your API Title")
                .description("Your API Description")
                .version("1.0.0")
                .build();
    }
}

• @Configuration: 이 클래스가 스프링의 구성 클래스임을 나타냅니다.
• @EnableSwagger2: Swagger 2를 사용하도록 활성화하는 어노테이션입니다.
• @Bean: 스프링의 Bean으로 등록되는 메서드를 정의합니다. Docket은 Swagger 설정을 구성하는 데 사용됩니다.
• api(): Docket 객체를 생성하고 설정을 구성하는 메서드입니다.
  • DocumentationType.SWAGGER_2: Swagger 2를 사용하여 문서화를 설정합니다.
  • apis(): API 컨트롤러 패키지 경로를 설정합니다. 해당 패키지에 있는 API 컨트롤러만 문서화됩니다.
  • paths(): 문서화할 API 경로를 선택합니다. PathSelectors.any()를 사용하면 모든 경로를 문서화합니다.
  • build(): Docket 객체를 빌드하여 반환합니다.
  • apiInfo(): API 정보를 구성하는 메서드입니다.
    • title(): API의 제목을 설정합니다.
    • description(): API에 대한 설명을 설정합니다.
    • version(): API의 버전을 설정합니다.
    • build(): ApiInfo 객체를 빌드하여 반환합니다.

 

 

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

오류발생

... 

 

 

해결방법:

application.properties에 이걸 추가한다!

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

 

 

 

 

/swagger-ui.html 여기로 접속하니

성공!!!!!!