Swagger 사용하기

프론트 페이지를 제공해주고, API들을 실제로 테스트 해 볼 수 있다. API 명세에 해당 되기도 한다. 

클라이언트 입장에선 백앤드 API 명세가 필수인데, 

해당 프론트 페이지에 접속 하기 위해서는 swagger-ui/index.html 또는 swagger-ui.html 로 접속하면 테스트 가능하다.

(설정 및 버전에 따라 다르다)

실 서버에서는 제거하고, 개발서버에서만 활성화 해야 한다.

 

• Gradle 추가

dependencies {
  implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.1'
}

• gradle 에 추가만 해주면 바로 사용이 가능하다.

 

• yaml 파일을 통해 개발 서버 활성, 실서버 비활성 방법

//application-dev.yaml
springdoc:
  swagger-ui:
    enabled: true
  api-docs:
    enabled: true
    
    
/application-prod.yaml    
springdoc:
  swagger-ui:
    enabled: false
  api-docs:
    enabled: false

 

설명 추가

•  @Tag
  • 클래스 어노테이션으로, 이름과 설명을 지정할 수 있다. 
• @Operation
  • 메소드 어노테이션으로, API에 대한 설명을 한다.
• @ApiResponses 와 @ApiResponse 를 통해 응답 코드 및 설명을 할 수 있다. 

@RestController
@RequestMapping("/users")
@Tag(name = "User", description = "사용자 관련 API")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "사용자 조회", description = "ID로 사용자를 조회합니다.")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "성공"),
        @ApiResponse(responseCode = "404", description = "사용자 없음")
    })
    public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
        UserDto user = new UserDto(id, "홍길동", "hong@test.com");
        return ResponseEntity.ok(user);
    }
}