[Spring Boot] Swagger UI 사용하기 (3.2.1 버전 기준)

💡Swagger UI?

API 명세서를 웹에서 문서화하여 볼 수 있도록 해주는 라이브러리

Spring Boot의 소스코드에서 Controller 의 어노테이션 (ex. @PutMapping,@RequestParam 등) 과 메소드 반환형을 스캔하여 문서화 해준다.

🔎 사용하기 ! (Spring Boot 3.2.1 버전 기준!)

build.gradle 에 dependency 추가

검색하면서 springfox 를 사용한다는 레퍼런스를 많이 봤는데,
❗️ springboot 3.0.0 이상부터는 springfox가 아닌 springdoc-openapi-ui 라이브러리 사용을 권장한다고 한다.

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

Spring Boot 실행 후 http://localhost:8080/swagger-ui/index.html 접속

성공!

---

🔎 Swagger 어노테이션 사용하기 (swagger 3 기준)

API 에 대한 설명을 추가하고 싶다면 어노테이션을 사용하면 된다.

✅ 메소드 설명 : @Operation

@Operation(summary="", description="")

ex)

    @GetMapping("/all")
    @Operation(summary="모든 사용자 학번 불러오기")
    public Iterable<users> list() { return users_Repository.findAll(); }

=> 이런식으로 설명이 추가됨!

✅ 파라미터 설명 : @Parameter

@Parameter : 해당 API Method 호출에 필요한 Parameter 설명 추가
@Parameters : 여러 개의 파라미터에 대한 설명이 필요한 경우 사용
ex)

@Parameters({
	@Paremter(
    	name="id",
        description="파라미터 설명"),
    @Parameter(
    	name="name",
        description="파라미터 설명"),
})

✅ API 그룹 분류 : @Tag

@Tag(name="", description="")
컨트롤러 클래스 위에 선언해주고, 설명을 써줄 수 있다.
ex)

@RestController
@Tag(name="users-controller",description = "로그인 관련 API")
@RequestMapping("/users")
public class usersController { ...

-> 다음과 같이 이름과 설명이 설정된다!