Swagger로 사랑받는 개발자 되기 [ Spring ]

 

들어가며

안녕하세요, 여러분! 오늘은 개발자로서 Swagger를 이용해 API 문서를 작성하는 방법과 이를 통해 사랑받는 개발자가 되는 방법에 대해 이야기해 보려고 합니다. 특히, Spring 프레임워크를 사용하는 여러분께 유용한 팁과 예제를 공유할 예정입니다. 그럼, 시작해볼까요?

Swagger란 무엇인가요?

Swagger는 API 문서를 자동으로 생성해주는 툴로, API의 설계 및 구현 과정에서 매우 유용하게 사용됩니다. Swagger를 사용하면, API의 명세를 쉽게 확인하고 테스트할 수 있어 개발자와 비개발자 모두에게 큰 도움이 됩니다. Spring 프레임워크와 결합하면 더욱 강력한 도구로 활용할 수 있습니다.

@Tag와 @SecurityRequirement

먼저, API 인터페이스를 정의하는 부분을 살펴보겠습니다.

@Tag(name = "코스 관련 API")
@SecurityRequirement(name = "Authorization")
public interface CourseApi {

• @Tag: 이 어노테이션은 API의 태그를 지정합니다. 태그는 API 문서를 그룹화하는 데 사용됩니다. 여기서는 "코스 관련 API"라는 이름으로 태그를 지정하였습니다.
• @SecurityRequirement: 이 어노테이션은 보안 요구 사항을 지정합니다. 여기서는 Authorization이라는 보안 요구 사항을 정의하여, 이 API가 인증을 필요로 한다는 것을 나타냅니다.

@Operation - API 메소드 정의

다음으로, API 메소드를 정의하는 부분을 살펴보겠습니다.

코스 전체 조회 API

@Operation(
    summary = "코스 전체 조회 API",
    parameters = {
        @Parameter(
            name = "country",
            description = "데이트 코스 지역 대분류",
            required = false,
            schema = @Schema(type = "string", allowableValues = {"SEOUL", "GYEONGGI", "INCHEON"}),
            example = "SEOUL"
        ),
        @Parameter(
            name = "city",
            description = "데이트 코스 지역 소분류",
            required = false,
            schema = @Schema(type = "string", allowableValues = { "SEOUL_ENTIRE", "GANGNAM_SEOCHO", ... }),
            example = "GANGNAM_SEOCHO"
        ),
        @Parameter(
            name = "cost",
            description = "필터링할 가격",
            required = false,
            schema = @Schema(type = "int"),
            example = "50000"
        )
    },
    responses = {
        @ApiResponse(
            responseCode = "200",
            content = @Content(
                schema = @Schema(implementation = CourseGetAllRes.class),
                examples = @ExampleObject(value = """
                    {
                        "courses": [
                            {
                                "courseId": 1,
                                "thumbnail": "",
                                "city": "건대/상수/왕십리",
                                "title": "Introduction to Java",
                                "like": 100,
                                "cost": 500,
                                "duration": 10
                            },
                            {
                                "courseId": 2,
                                "thumbnail": "",
                                "city": "건대/상수/왕십리",
                                "title": "Advanced Spring",
                                "like": 150,
                                "cost": 700,
                                "duration": 15
                            }
                        ]
                    }
                """)
            ),
            description = "요청이 성공했습니다."
        ),
        @ApiResponse(responseCode = "400", description = "잘못된 요청입니다.", content = @Content),
        @ApiResponse(responseCode = "401", description = "액세스 토큰의 형식이 올바르지 않습니다. Bearer 타입을 확인해 주세요.", content = @Content),
        @ApiResponse(responseCode = "401", description = "액세스 토큰의 값이 올바르지 않습니다.", content = @Content),
        @ApiResponse(responseCode = "401", description = "액세스 토큰이 만료되었습니다. 재발급 받아주세요.", content = @Content),
        @ApiResponse(responseCode = "405", description = "잘못된 HTTP method 요청입니다.", content = @Content),
        @ApiResponse(responseCode = "500", description = "서버 내부 오류입니다.", content = @Content)
    }
)
ResponseEntity<CourseGetAllRes> getAllCourses(
    @Parameter(required = false) final @ModelAttribute @Valid CourseGetAllReq courseGetAllReq
);

• @Operation: 이 어노테이션은 특정 API 메소드에 대한 설명을 추가합니다. summary 속성은 API 메소드의 간략한 설명을 제공합니다.
• @Parameter: API 메소드에서 사용하는 파라미터를 정의합니다. name, description, required, schema, example 등의 속성을 사용하여 파라미터에 대한 상세한 정보를 제공합니다.
• @ApiResponse: API 메소드의 응답을 정의합니다. 각 응답 코드에 대한 설명과 함께, 응답의 구조를 @Content와 @Schema를 통해 정의합니다.

@ExampleObject - 응답 예시

응답 예시는 API 사용자에게 실제 응답의 형태를 보여주기 위해 매우 중요합니다.

@ExampleObject(value = """
{
    "courses": [
        {
            "courseId": 1,
            "thumbnail": "",
            "city": "건대/상수/왕십리",
            "title": "Introduction to Java",
            "like": 100,
            "cost": 500,
            "duration": 10
        },
        {
            "courseId": 2,
            "thumbnail": "",
            "city": "건대/상수/왕십리",
            "title": "Advanced Spring",
            "like": 150,
            "cost": 700,
            "duration": 15
        }
    ]
}
""")

이렇게 응답 예시를 제공하면, API 사용자들은 실제 응답이 어떤 형태일지 쉽게 이해할 수 있습니다.

정렬된 코스 내역 조회 API

다음으로, 정렬된 코스 내역 조회 API를 살펴보겠습니다.

@Operation(
    summary = "정렬된 코스 내역 조회 API",
    parameters = {
        @Parameter(
            name = "sortBy",
            description = "데이트 코스를 인기순/최신순 으로 조회하는 Api입니다.",
            required = true,
            schema = @Schema(type = "string", allowableValues = {"POPULAR", "LATEST"}),
            example = "POPULAR"
        )
    },
    responses = {
        @ApiResponse(
            responseCode = "200",
            content = @Content(
                schema = @Schema(implementation = CourseGetAllRes.class),
                examples = @ExampleObject(value = """
                    {
                        "courses": [
                            {
                                "courseId": 1,
                                "thumbnail": "www.asdfasdfds.jpg",
                                "title": "5년차 장기연애 커플이 보장하는 성수동 당일치기 데이트 코스",
                                "city": "건대/상수/왕십리",
                                "like": 3,
                                "cost": 10,
                                "duration": 10
                            },
                            ...
                        ]
                    }
                """)
            ),
            description = "요청이 성공했습니다."
        ),
        ...
    }
)
ResponseEntity<CourseGetAllRes> getSortedCourses(
    @Parameter(required = true) final @RequestParam String sortBy
);

• sortBy 파라미터를 통해 인기순 또는 최신순으로 코스를 정렬하여 조회할 수 있습니다.
• 응답 예시는 동일하게 제공되어, 실제 응답의 형태를 이해할 수 있습니다

Swagger 인터페이스 구현후 Implements

Swagger 인터페이스를 구현했으면 이제 실제로 사용하는 class에 상속을 받아 사용해야하는데요 이처럼 상속을 받아서 사용하시면 됩니다!

public class CourseController implements CourseApi {
    private final CourseService courseService;
    private final AsyncService asyncService;

    @GetMapping
    public ResponseEntity<CourseGetAllRes> getAllCourses(
            final @ModelAttribute @Valid CourseGetAllReq courseGetAllReq
    ) {
        CourseGetAllRes courseAll = courseService.getAllCourses(courseGetAllReq);
        return ResponseEntity.ok(courseAll);
    }
}

Swagger 예시 

마무리

이렇게 Swagger를 이용해 API 문서를 작성하면, API 사용자가 이해하기 쉽게 문서를 제공할 수 있습니다. 이는 개발자와 비개발자 모두에게 큰 도움이 되며, 효율적인 협업을 가능하게 합니다. 여러분도 Swagger를 통해 사랑받는 개발자가 되어보세요!

감사합니다! 😃