스프링 부트 swagger 3 적용하기

spring boot swagger 3

1. 의존성 설정

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.9</version>
</dependency>

 

2. 설정 작업

적절한 프로파일의 application-properties 에 적용

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path-/swagger-ui.html
springdoc-swagger-ui.disable-swagger-default-url=true
springdoc.swagger-ui.diplay-query-params-without-oauth2=false
//springdoc.packages-to-scan=com.example.package, com.example.another.package
//springdoc.path-to-match=/some/url/**, /another/url/**

위 설정 중 가장 중요한 설정이

springdoc.packages-to-scan와 springdoc.path-to-match 이다.

둘중 하나만 있으면 된다.

 

상황별 사용 설정 정보

• 패키지 경로의 컨트롤러 전부 노출 : springdoc.packages-to-scan
• api 요청 경로로 일부 컨트롤러 노출 : springdoc.path-to-match

상세 프로퍼티 내용은 다음 링크 참조

https://springdoc.org/#swagger-ui-configuration

https://springdoc.org/#springdoc-openapi-core-properties

 

3. 컨트롤러, 메소드 어노테이션 작업

@Tag(name = "컨트롤러 이름", description = "컨트롤러 설명")
@RestController
public class SampleController{
	@Operation(summary = "요약 내용", description = "설명")
  public ResponseEntity<Object> methodSample(@RequestBody SampleDto dto){
		...
	}
}

 

@Tag : 컨트롤러 그루핑 하는 어노테이션

@Operation : 컨트롤러 내의 메소드의 정보를 설정

 

추가 적인 정보는 해당 링크 참조

https://oingdaddy.tistory.com/272

Springboot에서 API Docs (Springdoc) 사용하는 방법 (2)

 

4. swagger 페이지 접속하기

{schem}://{host}:{port}/swagger-ui.html

ex) http://localhost:8080/swagger-ui.html