[BE] Swagger Docs

Swagger 문서

---

📖 Swagger 문서 작성법

경로

Swagger docs 문서들은 application 모듈 > 각 도메인 > controller 하위에 위치 시킵니다.

Production Code

controller는 swagger 문서화를 위해 controller 이름 + Docs라는 이름으로 interface를 만들고 상속받습니다(사실 굳이 docs라는 이름을 안붙여도 되지만, 통일성을 위해 요청드립니다!).

@RestController
@RequestMapping("/test/swagger")
class TestController: TestControllerDocs {
    @GetMapping
    override fun ping(): String {
        return "Pong!"
    }
}

Swagger Docs

Swagger 관련 어노테이션은 모두 interface에서 작업합니다.
이 때, 여러개의 API 가 존재하여 한 파일에 지나치게 많은 API 명세가 들어가 가독성이 떨어지는 것을 피하기 위해 각 api 들은 별도의 인터페이스로 만들고 xxxControllerDocs 가 이를 상속받습니다.

@Tag(name = "점주 Test Controller", description = "점주 Test Controller 입니다.")
interface TestControllerDocs: Ping

interface Ping {
    @Operation(
        summary = "TestApi의 예시",
        description = "TestApi 예시입니다.",
    )
    @Parameters(
        value = [
            Parameter(name = "TestParameter", description = "TestParameter 입니다."),
        ],
    )
    @ApiResponses(
        value = [
            ApiResponse(responseCode = "200", description = "OK"),
        ],
    )
    fun ping(): String
}