Swagger와 API 명세

 

1. Swagger / OpenAPI (가장 많이 사용됨)

Swagger란?

• API 명세를 자동 생성해주는 도구
• OpenAPI 스펙을 바탕으로 UI를 통해 확인하고 테스트 가능

Spring Boot 연동 방법

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

// http://localhost:8080/swagger-ui/index.html 에서 확인 가능

---

장점

자동 문서화	컨트롤러, DTO에 붙인 @Operation, @Parameter 등으로 자동 생성
UI 제공	Swagger UI에서 API 직접 테스트 가능
OpenAPI 3.0 스펙 지원	다른 툴과 연동 쉬움 (Postman, Notion 등)

---

예시

@Operation(summary = "회원 조회", description = "ID로 회원을 조회합니다.")
@GetMapping("/user/{id}")
public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
    ...
}

이렇게 하면 Swagger UI에 문서 + 테스트 폼이 자동 생성됨

---

2. REST Docs (문서화 특화, Swagger 대안)

Spring에서 제공하는 정적 문서 생성 도구

테스트 코드와 함께 문서를 자동 생성함

Swagger보다 문서 품질을 세밀하게 제어 가능 (PDF, HTML 등)

단점: 설정이 복잡하고 진입장벽 높음
장점: 보안 민감한 API에도 적용 가능 (UI 제공 없음)

---

3. Postman + OpenAPI 연동

Swagger에서 생성한 OpenAPI YAML/JSON을 Postman에 불러와서 테스트

팀원 간 테스트 공유에 유용 (프론트엔드도 쉽게 확인 가능)

---

4. Notion, Stoplight 등 협업 중심 도구

디자이너/기획자와 협업할 땐 문서형식 API 명세서도 병행

Swagger + Notion 구조로 많이 사용

---

실무 추천 조합

springdoc-openapi	Swagger 자동 문서화 + UI 테스트
Postman	클라이언트 API 테스트 & 공유
Spring REST Docs	고품질 문서가 필요한 경우
Notion	간단한 문서 협업용으로 병행

---

보너스: Swagger + JWT 헤더 적용법

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
        .components(new Components()
            .addSecuritySchemes("bearerAuth",
                new SecurityScheme()
                    .name("Authorization")
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")));
}

Swagger UI에서 Authorization 입력창 생김!

---

 

1단계: 의존성 추가 (Spring Boot 3.x 기준)

// build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

설치 후 ./gradlew build 또는 IntelliJ에서 "Load Gradle Changes" 눌러주면 OK.

---

2단계: Swagger 기본 접속 주소

설정 없이도 다음 경로에서 바로 Swagger UI 확인 가능:

http://localhost:8080/swagger-ui/index.html
OpenAPI 문서: http://localhost:8080/v3/api-docs

---

3단계: Swagger 기본 설정 커스터마이징 (선택)

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("Sisyphus API 명세서")
                .version("1.0")
                .description("단어장 프로젝트를 위한 Swagger 문서입니다."))
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
            .components(new Components()
                .addSecuritySchemes("bearerAuth",
                    new SecurityScheme()
                        .name("Authorization")
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")));
    }
}

위 설정을 하면 Swagger UI에서 JWT 입력 창도 생겨서
인증이 필요한 API를 테스트할 수 있어요

---

4단계: Controller & DTO에 어노테이션 추가

Controller

@Tag(name = "회원 API", description = "회원 관련 기능들")
@RestController
@RequestMapping("/api/user")
public class UserController {

    @Operation(summary = "회원 조회", description = "ID로 회원 정보를 조회합니다.")
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
        ...
    }
}

DTO 

public class UserResponse {

    @Schema(description = "회원 고유 ID", example = "1")
    private Long id;

    @Schema(description = "회원 이메일", example = "heesoo@example.com")
    private String email;

    @Schema(description = "회원 이름", example = "희수")
    private String name;
}

---

5단계: Swagger 사용법

사용 방법

1. localhost:8080/swagger-ui/index.html 접속
2. API 목록에서 원하는 API 클릭
3. Try it out 누르면 → 파라미터 입력 가능
4. Execute 누르면 → 실제 요청 및 응답 확인 가능 (헤더, 바디 등 포함)

---

6단계: JWT 인증 붙인 API 테스트하기

1. Swagger UI 오른쪽 상단에 Authorize 버튼 클릭
2. Bearer {토큰} 형식으로 입력 (Bearer eyJ...)
3. 인증이 필요한 API 테스트 가능!

---

7단계: API 자동 문서로 팀과 공유하기

• /v3/api-docs → JSON 다운로드 가능
• https://editor.swagger.io/ 에 복붙해서 시각화 가능
• Postman / Notion에 OpenAPI 가져오기 가능

---

 

@Operation 이란?

@Operation(summary = "간단한 요약", description = "상세한 설명")

• summary: UI에 짧게 요약되는 설명 (한 줄 제목)
• description: 자세한 설명 (줄글 설명)

Swagger UI에서 다음 위치에 표시됨:

summary	API 명세의 제목 부분
description	펼쳤을 때 자세한 설명 칸

---

기본 사용 예시

@Operation(
    summary = "회원 조회 API",
    description = "ID 값을 이용해서 특정 회원 정보를 조회합니다."
)
@GetMapping("/user/{id}")
public ResponseEntity<UserResponse> getUserById(@PathVariable Long id) {
    ...
}

---

자주 쓰는 옵션들

@Operation(
  summary = "회원 생성",
  description = "신규 회원을 등록합니다.",
  tags = { "User" },
  responses = {
    @ApiResponse(responseCode = "200", description = "성공"),
    @ApiResponse(responseCode = "400", description = "잘못된 요청"),
    @ApiResponse(responseCode = "500", description = "서버 오류")
  }
)

주요 속성 설명:

summary	API의 제목 (한 줄 요약)
description	상세 설명
tags	Swagger UI에서 그룹 묶기 용도
responses	응답 상태 코드별 설명 (@ApiResponse와 함께)

---

@Parameter와 함께 쓰는 예

@Operation(summary = "회원 검색")
@GetMapping("/user/search")
public ResponseEntity<List<UserResponse>> searchUser(
    @Parameter(description = "검색할 이름", example = "희수")
    @RequestParam String name
) {
    ...
}

→ 이렇게 하면 Swagger UI에서 파라미터 칸에 이름과 예시까지 보여줘요!

---

실전 패턴 추천

Controller 클래스 위	@Tag(name = "User", description = "회원 API")	API 그룹명
메서드 위	@Operation(...)	한 API 설명
파라미터	@Parameter(...)	@PathVariable, @RequestParam
DTO 필드	@Schema(...)	@RequestBody, 응답 DTO용

---

전체 조합

@Tag(name = "회원 API", description = "회원 관련 기능 제공")
@RestController
@RequestMapping("/api/user")
public class UserController {

    @Operation(
        summary = "회원 조회",
        description = "회원 ID를 기반으로 회원 정보를 반환합니다.",
        responses = {
            @ApiResponse(responseCode = "200", description = "조회 성공"),
            @ApiResponse(responseCode = "404", description = "회원 없음")
        }
    )
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(
        @Parameter(description = "회원 ID", example = "1")
        @PathVariable Long id
    ) {
        ...
    }
}

@Operation	API 메서드 설명
@Parameter	Path/Query 파라미터 설명
@Schema	DTO 필드 설명
@ApiResponse	응답 상태코드 문서화
@Tag	API 그룹 분류