Swagger

Swagger란?

Swagger는 REST API의 설계, 문서화, 테스트, 개발을 위한 오픈소스 도구 세트입니다. Swagger는 API를 표준화하고, 개발자와 클라이언트 간의 의사소통을 원활하게 하는 데 도움을 줍니다. 현재는 OpenAPI Specification (OAS)의 일부로 발전했습니다.

---

Swagger의 주요 특징

1. API 문서화 자동화

   • API를 코드에서 자동으로 읽어들여 HTML 형식의 사용자 친화적인 문서를 생성합니다.

2. API 테스트 및 시뮬레이션

   • Swagger UI를 사용하여 브라우저에서 직접 API를 테스트할 수 있습니다.

3. 언어 및 프레임워크 독립적

   • 다양한 언어(Java, Python, Node.js 등)와 프레임워크(Spring Boot, Flask 등)에서 지원됩니다.

4. REST API 표준화

   • Swagger는 OpenAPI Specification을 기반으로 API의 구조와 작동 방식을 정의합니다.

---

Swagger 구성 요소

1. Swagger Editor

   • OpenAPI Specification에 따라 API 문서를 작성하고 수정할 수 있는 도구.

2. Swagger UI

   • API 문서를 브라우저에서 시각적으로 볼 수 있게 해주는 도구.
   • REST API 테스트 기능도 제공.

3. Swagger Codegen

   • API 정의 파일로부터 클라이언트 SDK나 서버 스텁 코드를 자동 생성.

4. SwaggerHub

   • 팀 단위의 API 설계와 협업을 위한 클라우드 기반 플랫폼.

---

Swagger와 OpenAPI Specification (OAS)

Swagger는 OpenAPI Specification을 기반으로 동작합니다.
OpenAPI Specification은 REST API를 기술하기 위한 표준 형식(JSON 또는 YAML)을 제공합니다.

예제 OAS 문서 (YAML):

openapi: 3.0.0
info:
  title: Example API
  description: Example API 문서입니다.
  version: "1.0.0"
servers:
  - url: http://api.example.com/v1
paths:
  /users:
    get:
      summary: 모든 사용자 조회
      responses:
        "200":
          description: 성공
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

---

Swagger UI 사용 예제 (Spring Boot)

Spring Boot에서 Swagger를 설정하려면 Springfox 또는 Springdoc 라이브러리를 사용할 수 있습니다.

Spring Boot Swagger 설정 (Springdoc OpenAPI)

1. Maven 의존성 추가

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-ui</artifactId>
       <version>1.7.0</version>
   </dependency>

2. API 문서 자동 생성
   Spring Boot 애플리케이션을 실행하면 기본적으로 /swagger-ui.html에서 Swagger UI를 확인할 수 있습니다.

3. 예제

• SwaggerConfig
  

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

	@Configuration
	@OpenAPIDefinition(info = @Info(title = "API 서버", version = "v1"))
	public class SwaggerConfig {
    	@Bean
    	public GroupedOpenApi openAPI() {
        	return GroupedOpenApi.builder()
                .group("order")
                .pathsToMatch("/order/**")
                .build();
    	}
 }

• Controller

   import org.springframework.web.bind.annotation.*;

  @RestController
  @RequestMapping("/order")
  public class OrderController {

    	@PostMapping
    	@Operation(summary = "Create an Order", description = "새로운 주문을 생성합니다.")
    	@ApiResponse(responseCode = "200", description = "성공적으로 주문이 생성되었습니다.")
    	@ApiResponse(responseCode = "400", description = "잘못된 요청입니다.")
    	public ResponseMessage<OrderResponseDto> createOrder(
            	@RequestBody @Valid OrderDto orderDto) {
        // 구현 코드
    }
   }

4. Swagger UI 결과
   • /order에 대한 메소드가 Swagger UI에 표시되고, 요청과 응답을 테스트할 수 있습니다.

---

Swagger 사용의 장점

1. API 문서의 자동화
   개발자가 별도로 문서를 작성할 필요 없이, 코드에서 API 정의를 읽어 자동으로 문서를 생성합니다.

2. 개발자 및 클라이언트 간 의사소통 향상
   Swagger UI를 통해 클라이언트와의 API 설계 논의를 쉽게 진행할 수 있습니다.

3. 빠른 테스트 및 디버깅
   API의 요청과 응답을 UI에서 바로 확인하고, 테스트할 수 있습니다.

4. 코드 생성 지원
   클라이언트 SDK 및 서버 스텁 코드를 자동 생성하여 개발 속도를 높입니다.

---

Swagger 사용의 한계

1. 복잡한 설정
   대규모 프로젝트에서는 Swagger 설정이 복잡해질 수 있습니다.

2. 리소스 소비
   Swagger UI를 실행하면 애플리케이션의 메모리와 CPU를 추가적으로 소모할 수 있습니다.

3. 보안 이슈
   개발 중이거나 민감한 API는 Swagger UI를 통해 공개되지 않도록 보호가 필요합니다.

---

Swagger를 사용해야 하는 이유

• 효율성 향상: API 설계와 문서화를 단일 프로세스로 통합.
• 테스트 편의성: 개발자와 QA가 쉽게 API를 테스트.
• API 표준화: OpenAPI Specification을 통해 명확하고 일관된 API 설계.

Swagger는 REST API를 효율적으로 설계, 문서화, 테스트하기 위한 필수 도구입니다.

추가 학습 자료

• Swagger UI
• Swagger/OpenAPI를 사용한 ASP.NET Core 웹 API 설명서
• [Spring Boot 3] SpringDoc과 Swagger를 이용해 API 문서화 자동화하기