Swagger란? (with JPA)

JOY·2024년 11월 14일

[Swagger]

목록 보기

1/1

Swagger

API 문서화 도구이자 테스트 도구
RESTful API의 문서화 및 테스트를 위해 사용하며,
API 엔드포인트와 각 엔드포인트에서 제공하는 기능 및 요청/응답 방식을 쉽게 확인할 수 있다.
주로 API의 기능을 개발하면서 화면(프론트엔드) 구현이 완료되지 않았을 때
백엔드의 API가 제대로 동작하는지 확인하는 용도로 사용된다.

Swagger의 주요 기능 및 장점

API 문서화
Swagger는 코드에 작성된 API 메서드를 자동으로 문서화해줍니다.
각 메서드가 어떤 요청을 받는지, 어떤 응답을 반환하는지,
필요한 파라미터는 무엇인지 등을 한 눈에 확인이 가능하다.
API 요청과 응답 형식 테스트
Swagger UI에서는 문서화된 API를 실제로 호출해볼 수 있는Try it out 기능을 제공하여,
백엔드에서 API를 구현한 후, 서버에 실제 요청을 보내고
응답을 JSON 형식으로 서버의 실제 응답 값을 미리 확인할 수 있다.
엔드포인트 설명
각 엔드포인트가 어떤 HTTP 메서드를 사용하고,
어떤 데이터가 필요한지, 어떤 응답을 받는지 등을 상세히 설명해준다.
자동화된 문서 유지
코드에 주석을 추가하거나 OpenAPI 사양을 정의해 두면,
Swagger는 이를 기반으로 문서를 자동 생성하고 유지하고
API가 변경되면 문서도 함께 업데이트된다.

REST 컨트롤러 생성 예시

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @GetMapping
    public List<User> getAllUsers() {
        return userRepository.findAll();
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userRepository.save(user);
    }

    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userRepository.findById(id).orElse(null);
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User userDetails) {
        User user = userRepository.findById(id).orElse(null);
        if (user != null) {
            user.setName(userDetails.getName());
            user.setEmail(userDetails.getEmail());
            return userRepository.save(user);
        }
        return null;
    }

    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        userRepository.deleteById(id);
    }
}

Swagger UI의 API 문서

GET /api/users: 모든 사용자 목록 조회
POST /api/users: 새로운 사용자 생성
GET /api/users/{id}: 특정 사용자 조회
PUT /api/users/{id}: 특정 사용자 정보 수정
DELETE /api/users/{id}: 특정 사용자 삭제

Swagger UI에서 문서화된 엔드포인트 예시

GET /api/users 엔드포인트

GET /api/users
---
Description:
    Returns a list of all users.
Parameters:
    None
Responses:
    200 OK:
        [
            {
                "id": 1,
                "name": "Alice",
                "email": "alice@example.com"
            },
            {
                "id": 2,
                "name": "Bob",
                "email": "bob@example.com"
            }
        ]
    404 Not Found:
        {
            "error": "No users found"
        }

Swagger UI에서의 상세 설명

필드	내용
HTTP 메서드	GET
URL 경로	/api/users
설명	사용자 목록을 조회하고, 이를 JSON 형식의 배열로 반환합니다.
파라미터	없음
응답 코드	200 OK 또는 404 Not Found
응답 본문 예시	성공 응답(200)[{"id": 1, "name": "Alice", "email": "alice@example.com"}, ...]에러 응답(404){"error": "No users found"}

Swagger UI 화면에서의 모습

GET /api/users - "Returns a list of all users"
Parameters: 설명 및 필요 여부
Responses:
200 OK - [{"id": 1, "name": "Alice", "email": "alice@example.com"}, ...]
404 Not Found - {"error": "No users found"}

일부 개념 진짜 쉽게 이해하기!

API는 프로그램들이 서로 정보를 주고받고 협력할 수 있게 도와주는 "약속" 같은 것.
Swagger는 그 약속을 정리해 주는 도구!

👉 백엔드 개발자가 API를 만든다는 건,
앱과 서버가 서로 정보를 주고받을 수 있는 방법을 코드로 작성해 놓는 것과 같다!

메서드와 API

@RestController
public class UserController {
    @GetMapping("/api/users")
    public List<User> getAllUsers() {
        // 이 메서드는 사용자 목록을 반환하는 기능을 합니다.
        return userService.getAllUsers();
    }
}

GET /api/users 엔드포인트에서 GET 은 HTTP 메서드이고,
이 메서드는 서버 측의 메서드 (예: getAllUsers())를 호출할 수 있게 해준다.

👉 API 엔드포인트는 메서드를 호출하는 외부의 요청을 받는 역할을 하고,
그 요청을 처리하기 위해 서버 측의 메서드가 실행된다.

JOY

Just Do IT ------- 🏃‍♀️