서버/Spring

[Spring] Spring Doc Swagger 문서 자동화

sm.jeon 2024. 3. 13. 00:53
반응형

Swagger?

REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이되는 OpenAPI 사양을 중심으로 구축 된 오픈 소스 도구 세트.

Controller의 어노테이션 정보를 통해 API 정보를 읽어 문서를 생성한다.

 

Spring Doc

Swagger는 Java 전용 툴이 아니기 때문에, Spring 환경에서 사용하기 위해서 추가적인 작업을 해야 한다. 이 작업을 대신 해주는 라이브러리이다.

Spring Doc, Spring Fox가 있는데, Spring Fox는 2020년에 업데이트를 멈췄다 하니, Spring Doc을 쓰는 게 나아보인다.

 

Swagger 사용 설정하기

@Configuration
class SwaggerConfig {
    @Bean
    fun openApi() = OpenAPI().components(Components()).info(Info().title("title").description("description").version("1.0.0"))
}

 

application.properties

swagger-ui.path=/
swagger-ui.disable-swagger-default-url=true
swagger-ui.display-request-duration=true
swagger-ui.operations-sorter=alpha

 

Controller 설정하기

@Tag(name = "Example")
@RestController
@RequestMapping("/example")
class ExampleController {
    @GetMapping("/get")
    fun getFunction() {

    }

    @PostMapping("/post")
    fun postFunction() {

    }

    @PutMapping("/put")
    fun putFunction() {

    }

    @PatchMapping("/patch")
    fun patchFunction() {

    }
}

 

Swagger 문서 확인하기

 

/swagger-ui/index.html 에 접속하면 생성된 문서를 확인할 수 있다.

각 API를 클릭하면, 파라미터와 응답 코드, 응답 본문을 확인할 수 있다.

파라미터와 응답 본문은, JSON 형태로 제공된다.

 

추가적인 정보 제공하기

API, 문서 등 추가적인 정보가 필요하다면, 알맞는 어노테이션을 붙여 추가적인 정보를 제공할 수 있다.

  • @Tag - Controller에 붙여 하위 API를 그룹핑한 것에 이름을 붙일 수 있다.
  • @XXXMapping - API의 Http 메서드가 무엇인지와 경로 정보를 제공한다.
  • @ApiResponses - 각 API 메서드에 사용하며, 응답 코드와 설명을 제공한다.
  • @ApiOperation - 각 API 메서드의 추가 정보를 제공한다.
  • @Parameter - API의 파라미터에 사용하며, 파라미터에 대한 추가적인 정보를 제공한다. 문서에 표시하지 않기 위한 hidden 속성만 사용해 봤다.
  • @Schema - JSON으로 변환되는 클래스에 설명을 추가 제공한다.

 

반응형