자동문서화 - Swagger

학습 배경

개발 초기.

계속해서 api 내용이 바뀐다.

 

Front Controller 인 디스패처 서블릿은 제쳐 두고,

클라이언트가 보낸 값을 받아오고 처리하는 Controller 계층에서

 

어떻게 값을 받아오고

어떤 값을 값을 받아오고

필요 정보는 무엇인지

무엇을 반환하는지 등을 자동으로 문서화 해주는 기술. SWAGGER 되시겠다.

---

미리보기

설정 완료 후, 브라우저를 통해 해당 경로로 접속하면 아래와 같은 정보를 확인할 수 있다.

localhost:8080/swagger-ui/index.html

 

SWAGGER

목적

• API 문서화
  • 자동화 : api의 스펙을 자동으로 문서화한다. 자동화된 문서화 기능을 통해 api 사용법을 쉽게 터득할 수 있다. 문서작업에 손도 덜 탄다.
  • 명확한 설명 : api EndPoint 에 대한 설명이 제공된다. 
• 인터렉티브 UI 제공
  • 테스트 기능 : Swagger ui 를 통해 브라우저에서 직접 api를 테스트할 수 있다.

실습 환경

java - 17

spring boot - 3.2

** 버전에 따라 호환 문제가 발생할 수 있다.

 

DI - maven

<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
			<version>2.0.2</version>
		</dependency>

 

DI - gradle

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

 

 

설정 클래스

@OpenAPIDefinition(
        info = @Info(title = "MaterialManagementApp", version = "v1"))
@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi api() {
        String[] paths = {"/**"};

        return GroupedOpenApi.builder()
                .group("materials")
                .pathsToMatch(paths)
                .build();
    }
}

 

 

@Slf4j
@RequiredArgsConstructor
@RequestMapping("/materials")
@RestController
public class MaterialController {

    private final MaterialService materialService;

    @PostMapping()
    public ResponseEntity<?> addMaterial(@RequestBody @NotNull List<@Valid AddRequestDto> dto){
        List<AddResponseDto> result = materialService.add(dto);
        return new ResponseEntity<List<AddResponseDto>>(result,HttpStatus.OK);
    }
}

 

 

 

 

 

테스트 기능

 

 

참조자료

https://github.com/fadykuzman/swagger-demo/blob/main/pom.xml

https://medium.com/@f.s.a.kuzman/using-swagger-3-in-spring-boot-3-c11a483ea6dc

Using Swagger 3 in Spring Boot 3

 

swagger-demo/pom.xml at main · fadykuzman/swagger-demo