Swagger 연동 및 설정 방법

Spring Boot + Swagger 연동 방법과 간단한 설정 방법

*maven project에서 springdoc(swagger3)으로 진행

*자세한 설명 생략

 

 

▷ Swagger3 연동

*dependency 이후 바로 사용 가능

 

① pom.xml springdoc dependency

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

 

 

▷ Swagger3 명세서 작성 방법

 

*Swagger3 주요 Annotation

태그	속성	설명
@Tag		Controller 명세
	name	API 그룹 명
	description	API 그룹 설명
@Operation		API 명세
	summary	API 설명
	description	API 상세 설명
@Schema		Model 명세
	description	Model 설명
	defaultValue	Model default value 지정

 

① Controller, API 명세

*@Tag, @Operation

 

/**
 * 피플 카운터 테스트 데이터 생성 Controller
 */
@Slf4j
@RestController
@RequestMapping("bhs")
@Tag(name = "MKD", description = "테스트 데이터 생성 서비스")
public class MKD1001Controller extends CmmController {

    @Autowired
    private MKDService mkdService;

    @PostMapping("/mkd/mkd1001.do")
    @Operation(summary = "BHS-MKD-1001", description = "피플 카운터 테스트 데이터 생성")
    public MKD1001ResVO mkd1001(@RequestBody MKD1001ReqVO reqVO, HttpServletRequest req) {

        MKD1001ResVO resVO = new MKD1001ResVO();

        try {
            /** 요청 값 체크 */
            if( !"0000".equals(fieldsCheck(req, reqVO, resVO).getResultCode()) ) { return resVO; };
            
            /** 피플 카운터 테스트 데이터 생성 */
            resVO = mkdService.getMKD1001(reqVO);
            
        } catch (Exception e) {
            resVO.ERR_9999();
            log.error("MKD1001 ERR Message :", e);
        }

        return resVO;
    }
}

 

② Model 명세

*@Schema

 

/**
 * 피플 카운터 테스트 데이터 생성 요청 VO
 */
@Getter
@Setter
@ToString
@Schema(description = "피플 카운터 테스트 데이터 생성 요청 VO")
public class MKD1001ReqVO extends CmmReqVO {

    /** 시작 날짜 */
    @JsonProperty("startDate")
    @Schema(description = "시작 날짜(yyyyMMdd)", defaultValue = "20230101")
    public String startDate;

    /** 종료 날짜 */
    @JsonProperty("endDate")
    @Schema(description = "종료 날짜(yyyyMMdd)", defaultValue = "20231231")
    public String endDate;

    /** 생성 개수 */
    @JsonProperty("loopCnt")
    @Schema(description = "생성 개수", defaultValue = "1")
    public Integer loopCnt;

}

 

③ Swagger-ui 설정 방법

*SwaggerConfig 파일 생성

*아래 소스는 Swagger UI에서  API를 그룹화하여 구분 

*많은 설정이 있지만 여기서는 OpenAPIDefinition , GroupedOpenApi 설정만 다룸

 

*@OpenAPIDefinition 사용 속성

태그	속성	설명
@Info		문서 설명
	titile	문서 제목
	version	문서 버전

 

* GroupedOpenApi 사용 속성

속성	설명
group	그룹 명(Swagger 문서 definition 명)
pathsToMatch	그룹에 속할 API URI Paths
pathsToExclude	그룹에서 제외할 API URI Paths

 

/**
 * Swagger3
 * 
 */
@OpenAPIDefinition
( info = @Info(title = "[행태분석 솔루션] API 명세서", version = "0.1"))
@Configuration
public class Swagger3Config {

    /** API Group */
    @Bean
    public GroupedOpenApi groupedOpenApi() {
        return GroupedOpenApi.builder()
                .group("v0.1-BehaviorAnalysis")
                .pathsToMatch("/**")
                // .pathsToExclude("/bhs/mkd/**")
                .build();
    }

    /** Test Data Make Group */
    @Bean
    public GroupedOpenApi mkdOpenApi() {
        return GroupedOpenApi.builder()
                .group("v0.1-MakeTestData")
                .pathsToMatch("/bhs/mkd/**")
                .build();
    }

}

 

 

▷ 결과 Swagger3 UI

*http://IP+포트/swagger-ui/index.html 

 

 

 

▷ 참고

[Java/Library] Swagger 이해하고 적용하기 : SpringDoc openAPI UI

 

 

▷ 관련 글

Swagger 란?

Swagger3 JWT 인증 설정