Swagger씨, API 문서 작성해주세요 !

이번 포스팅에선 API 문서를 자동화해주는 Swagger에 대해 알아볼 것이다. 

 

API 문서는 왜 작성할까?

• 단순 문서화
• 개발 협업(프론트 개발자 - 백엔드 개발자)
• 버전 관리
• 테스트

예전에 팀 프로젝트에서 모바일 개발자님에게 API 공유를 위해 API 명세서를 일일이 노션으로 작성한 적이 있다.
당시 문서화하면서 머리가 나쁘면 몸이 고생한다는 그 말이 생각났다.
하지만 당시에는 아는 게 없으니 별 다른 수가 없어서 그냥 했었다.

 

멤버 등록 API를 문서화해 보자

build.gradle

/* Swagger */
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

 
application.yml

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    path: /swagger-ui.html

 
MemberApiController.createMember()

@Operation(summary = "멤버 등록", description = "새로운 멤버를 등록합니다.")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "멤버 등록 완료"),
    @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터")
})
@PostMapping("/api/v1/member")
public ResponseDto<?> createMember(
        @io.swagger.v3.oas.annotations.parameters.RequestBody(
                description = "멤버 등록 요청 DTO",
                required = true,
                content = @Content(schema = @Schema(implementation = MemberRequestDto.CREATE.class)))
        @RequestBody MemberRequestDto.CREATE dto) throws NoSuchElementException, Exception {
    service.createMember(dto);

    return ResponseDto.ofSuccess("멤버 등록에 성공했습니다.");
}

• @Operation에는 API에 대한 요약, 명세를 남길 수 있다.
• @ApiResponse에는 응답 코드와 명세를 남길 수 있고, 여러 개를 @ApiResponses로 묶을 수 있다.
• @RequestBody는 명세, 필수 여부, DTO 클래스를 매핑할 수 있다.
• 참고로 JSON 데이터를 객체에 매핑하는 @RequestBody와는 다른 클래스를 가리킨다.

 

MemberRequestDto

@Schema(description = "멤버 요청 DTO")
public class MemberRequestDto {
    @Getter
    @Setter
    @Schema(description = "멤버 등록 요청 DTO")
    public static class CREATE {
        @Schema(description = "멤버 이메일")
        private String email;
        
        @Schema(description = "멤버 비밀번호")
        private String password;
        
        @Schema(description = "멤버 이름")
        private String name;
        
        @Schema(description = "멤버 명세")
        private String description;
    }
}

• 컨트롤러에서 DTO 클래스를 매핑하고서 DTO에도 @Schema를 통해 클래스, 필드 별 명세를 남겨야 한다.
   

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

• 위 이미지처럼 API에 대한 계약 정보를 확인할 수 있다.
• 우측 상단에 [Try it out] 버튼을 통해 API를 실행해 볼 수도 있다. 

 

2025-03-06T22:17:46.322+09:00  INFO 18992 --- [nio-8080-exec-8] p6spy                                    : [statement] | 3 ms | 
    insert 
    into
        tbl_member
        (created_at, member_del_flag, member_description, modified_at, member_name, member_password, member_email) 
    values
        ('2025-03-06T22:17:46.253+0900', '0', 'string', '2025-03-06T22:17:46.253+0900', 'string', '$2a$10$QUS41KaM4NEv7EtG52XoEe76tY/cIyhMKIom5anPg7uPOsICPKR5O', 'string')
2025-03-06T22:17:46.333+09:00  INFO 18992 --- [nio-8080-exec-8] p6spy                                    : [commit] | 1 ms |

• [Execute] 버튼을 통해 실행할 수 있으며, 버튼을 누르면 실제로 서버에 쿼리가 실행된다.

 

• 위 이미지처럼 API 요청을 위한 Curl 명령어와 응답 관련 정보도 제공한다.

 

마치며

어제 포스팅한 P6Spy든 Swagger든 성능 저하를 위해 운영 환경에서는 사용하지 않도록 처리가 필요하다.
요즘 왜 이렇게 로깅이나 API 문서 자동화 같은 잡기술만 공부하고 싶을까 ㅋㅋ
진짜 해야 할 공부는 따로 있는데 🤪

 

이미지 출처

스웨거 (소프트웨어) - 위키백과, 우리 모두의 백과사전