Swagger(Springfox)

API 문서의 필요성

---

API 문서는 개발자들이 만들어 둔 API를 사용하여 서버의 비즈니스 로직과 데이터베이스에 접근할 때, API 사용 방법을 이해하고 다른 시스템과의 상호작용을 원활하게 하기 위해 필요하다. 이를 통해 효율적인 개발, 유지보수, 문제 해결이 가능해진다. 가장 잘 알려진 문서화 도구들은 REST API 개발 시에는 Swagger, GraphQL일 시에는 Playground 등이 있다. 

스프레드시트 등 수동 작성에 비교해 보았을 때 생산성 있고, 자동화된 형태의 문서를 생성할 수 있다는 장점이 있다.

 

 

Swagger란?

---

Swagger는 OpenAPI Specification을 기반으로 한 도구 모음으로, REST API를 설계, 빌드, 문서화, 소비할 수 있게 돕는다. 주요 도구로는 Swagger Editor, Swagger UI, Swagger Codegen 등이 있다.

 

https://swagger.io/docs/specification/about/

About Swagger Specification | Documentation | Swagger

🤔 OpenAPI
OpenAPI는 RESTful API를 정의하기 위한 사양이다. 이전에는 Swagger Specification으로 알려져 있었다. OpenAPI를 사용하면 API의 모든 엔드포인트 및 엔드포인트 작업(GET, POST...), 요청 및 응답 형식을 표준화된 방식으로 기술할 수 있다.


요약하자면 OpenAPI는 RESTful API를 정의하기 위한 표준 사양이다. 이 사양을 사용하면 API의 모든 엔드포인트, 요청 및 응답 형식을 표준화된 방식으로 기술할 수 있다.
Swagger는 OpenAPI 사양을 기반으로 API를 문서화하고 시각화하는 도구 모음이다. Swagger는 OpenAPI 문서를 작성하고, 이를 통해 API 문서를 자동으로 생성하며, API를 테스트하고 인터랙션할 수 있는 인터페이스를 제공한다.

 

 

Spring Boot에서 Swagger 사용 방법 

해당 방법은 Swagger 2.x 버전을 사용하여 API 문서를 작성하는 방법이다.

 

의존성 추가

dependencies {
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}

 

springfox-swagger2는 Swagger를 사용하여 API 문서를 생성하기 위한 의존성이다. 이 라이브러리는 OpenAPI 사양을 기반으로 API 문서를 자동 생성한다. 

springfox-swagger-ui는 생성된 OpenAPI 문서를 화면에 시각적으로 표시해주는 의존성이다. 이 라이브러리는 Swagger UI를 통해 브라우저에 API 문서를 쉽게 볼 수 있도록 도와준다.

 

✔️ Spring Boot 3.x 버전부터 Springdoc을 사용하는 것이 권장된다. Springfox는 Spring Boot 2.x 버전과의 호환성이 좋다.

 

Swagger 설정

'SwaggerConfig.java' 파일을 생성하여 설정을 추가한다.

// Swagger 설정을 위한 구성 클래스
@Configuration
@EnableSwagger2 // Swagger 2를 활성화하는 어노테이션
public class SwaggerConfig {

    // Docket Bean을 생성하여 Swagger 설정을 정의
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2) // Swagger 2 문서 타입 지정
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourpackage")) // 특정 패키지 내의 API만 문서화
                .paths(PathSelectors.any()) // 모든 경로를 문서화
                .build();
    }
}

 

애플리케이션 실행

애플리케이션을 실행한 후, 브라우저에서 다음 URL로 Swagger UI에 접근한다.

http://localhost:8080/swagger-ui.html

 

API 문서화

Controller 클래스에 Swagger 어노테이션을 추가한다.

// REST 컨트롤러 클래스
@RestController
@RequestMapping("/api") // "/api" 경로에 매핑
public class ExampleController {

    @ApiOperation(value = "Get example", notes = "Returns an example") // Swagger에 의해 API 문서에 추가될 설명
    @GetMapping("/example") // HTTP GET 요청을 처리, "/api/example" 경로에 매핑
    public String getExample() {
        return "example"; // "example" 문자열 반환
    }
}