[SpringBoot] swagger 란?, SpringBoot 연동 사용법

---

1.Swagger 란?

RESTful API를 설계, 문서화, 테스트, 관리하는 데 사용되는 오픈 소스 프레임워크이다.
직관적인 인터페이스와 자동화된 문서화를 제공한다.

 

 

 

 

 

2.SpringBoot와 연동

2-1.SpringDoc OpenAPI Starter WebMVC UI

Spring Boot 애플리케이션에서 OpenAPI 3.0 사양에 맞춘 API 문서를 자동으로 생성하고, Swagger UI를 통해 API를 시각화할 수 있게 해주는 라이브러리이다. 의존성을 그대로 복사해서 프로젝트 의존성에 추가한다.

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui

 

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

 

 

 

 

 

 

2-2.swagger UI 확인하기

이제 /swagger-ui.html 경로로 접속해본다.
만약 로컬 주소가 http://localhost:8080 이면 http://localhost:8080/swagger-ui.html으로 접속하면된다.

 

 

 

2-3.SwaggerConfig.java

Swagger UI와 OpenAPI를 설정하기 위한 클래스입니다.
API 명세서를 제공하기 위해 OpenAPI 객체를 사용합니다.

 

package com.example;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;

@Configuration
public class SwaggerConfig {
    
    // OpenAPI 설정을 정의하는 Bean
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components()) // Swagger 구성 요소 추가
                .info(apiInfo()); // API 정보 추가
    }

    // API의 제목, 설명 및 버전 정보를 설정하는 메서드
    private Info apiInfo() {
        return new Info()
                .title("API 제목") // Swagger UI에서 표시되는 API의 제목
                .description("api 테스트용입니다") // API에 대한 설명
                .version("1.0.0"); // API의 버전
    }
}

 

 

 

 

2-4.Swagger 어노테이션

2-4-1.@Tag

API를 그룹화하기 위해 사용되는 어노테이션입니다. 여러 API를 관련된 주제나 기능별로 그룹화하여 Swagger UI에 표시될 수 있습니다.

name: 태그의 이름
description: 태그에 대한 설명

@RestController
@Tag(name = "swageer 테스트용컨트롤러", description = "swagger테스트용입니다.") // Swagger에서 이 컨트롤러를 그룹화
public class SwaggerTestController {}

 

 

 

2-4-2.@Operation

API 엔드포인트의 동작 설명을 정의하는 어노테이션

summary: API의 간략한 설명
description: API의 상세 설명

@GetMapping("/hello")
    @Operation(summary = "반가움을보내요", description = "'Hello, World!'메시지를 반환") // API 설명 추가
    public String sayHello() {
        return "Hello, World!"; // 간단한 문자열을 반환
    }

 

 

 

2-4-3.@Parameter

API 엔드포인트의 파라미터를 정의하는 데 사용합니다.
description: 파라미터에 대한 설명
required: 해당 파라미터가 필수인지 여부 (기본값은 false)

@Operation(summary = "Get ID")
@GetMapping("/{id}")
public Long getId(
    @Parameter(description = "ID를받아온다", required = true) 
    @PathVariable Long id) {
        return id;
}

 

 

 

2-4-4.@ApiResponse

API 응답에 대한 설명을 작성할 수 있는 어노테이션입니다. 각 상태 코드와 해당 응답의 설명을 명시합니다.
responseCode: HTTP 상태 코드
description: 응답에 대한 설명

// GET 요청을 처리하는 API 엔드포인트
@GetMapping("/hello")
@Operation(summary = "반가움을보내요", description = "'Hello, World!'메시지를 반환") // API 설명 추가
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Request was successful")
})
public String sayHello() {
    return "Hello, World!"; // 간단한 문자열을 반환
}

 

 

2-4-5.@Schema

객체의 스키마를 정의하기 위해 사용됩니다. 주로 DTO 클래스나 모델 클래스에 적용하여 해당 클래스가 API 문서에서 어떤 구조로 표현될지 명시합니다.

 

package com.example.Model;

import io.swagger.v3.oas.annotations.media.Schema;

public class Testter {
    @Schema(description = "Unique identifier of the user", example = "123")
    private Long id;

    @Schema(description = "Name of the user", example = "John Doe")
    private String name;
}