Swagger 3.0 - 1

📝 Swagger 란?

Swagger는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다.

Swagger를 사용하게 되면 백엔드 개발자가 개발한 API를 프론트엔드 개발자가 Swagger가 생성한 페이지에 접속하여 둘러보고 테스트 해보며 직접 컨트롤 및 개발에 편리하게 적용할 수 있도록 만든 프레임워크라고 생각하면 될 것 같다.

🚩 SpringFox vs SpringDoc

SpringFox 와 SpringDoc은 둘 다 SpringFramework로 개발하는 프로젝트의 Swgger 문서를 간편하게 작성할 수 있게 도와주는 라이브러리이나 두 라이브러리의 Anntation들이 약간씩 다를뿐 기능을 거의 동일하다.
SpringFox는 Maven Repository 기준 2020년 7월 기준으로 업데이트가 끊겼으며, SpringDoc은 2023년 5월까지 업데이트가 진행되어있기 때문에 SpringDoc를 사용하기로 하였다.
또한 SpringDoc이 그룹간 API정렬이 가능하다고 하는데, 크게 의미 없는거 같으므로 신경쓰지 않아도 될 것 같다.

🚩 Swagger 3.0 - SpringDoc 설정

📝 pom.xml의 의존성 목록에 SpringDoc 라이브러리 추가

<!-- Swagger 3 SpringDoc Dependency-->
<dependency>
 	<groupId>org.springdoc</groupId>
 	<artifactId>springdoc-openapi-ui</artifactId>
 	<version>1.7.0</version>
</dependency>

• pom.xml의 의존성 목록에 SpringDoc 라이브버리를 추가해준다.
• 2023년 12월 기준 1.7.0 Version이 가장 최신 버전이다.

📝 SpringDoc 라이브러리 기본 설정

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String version,
                           @Value("${springdoc.title}") String title,
                           @Value("${springdoc.description}") String description) {
        Info info = new Info()
                .title(title)
                .version(version)
                .description(description);

        return new OpenAPI()
                .components(new Components())
                .info(info);
    }
}

• Swagger 3.0 - SpringDoc 라이브러리 사용하기 위해서 환경설정 클래스 파일을 생성해준다
• 환경설정 클래스 파일에 @Configuration Annotation를 설정해서 환경설정 클래스 파일을 인식시켜준다.
• @Bead Annotation으로 openAPI Method를 등록하여 Swagger 3.0 - SpringDoc 라이브러리 활성화 시켜준다.
• version, title, desciption 내용들을 @Value Annotation 이용하여 application.yml에서 관리하도록 한다.

📝 Application.yml를 이용한 설정

springdoc:
  version: v1.0.0
  title: Swagger 3.0 - SpringDoc Title
  description: Swagger 3.0 - SpringDoc Description
  packages-to-scan: com.boot.controller
  swagger-ui:
    path: /api-docs
  default-consumes-media-type: application/json; charset=UTF-8
  default-produces-media-type: application/json; charset=UTF-8

• version, title, desciption : Swaager 페이지에 표시될 버전, 제목, 내용
• package-to-scan : Swaager 페이지에 생성될 API가 정의된 Controller Package
• path : Swaager 페이지에 간편하게 들어갈 수 있는 경로
• default-consumes-media-type : 클라이언트로 부터 들어오는 API의 데이터의 Media Type
• default-produces-media-type : 클라이언트에게 제공될 API의 데이터의 Media Type

📝 Controller interface 설정

@Tag(name = "Template", description = "Template Description")
public interface ITemplateController {
    @Operation(summary = "Get Request Template", description = "HttpMethod.Get Method를 이용한 HTTP Request")
    @Parameters({
            @Parameter(name = "name", description = "TestGetRequestPayload 의 Test Field", required = true)
    })
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = UserInfoResponsePayload.class))),
            @ApiResponse(responseCode = "400", description = "bad request operation", content = @Content(schema = @Schema(implementation = ResponsePayload.class)))
    })
    ResponseEntity<ResponsePayload> httpMethodGet(@ParameterObject @ModelAttribute @Validated GetMethodRequestPayload payload, BindingResult error) throws CustomRunTimeException;

    @Operation(summary = "Post Request Template", description = "HttpMethod.Post Method를 이용한 HTTP Request")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = PostMethodResponsePayload.class))),
            @ApiResponse(responseCode = "201", description = "created operation", content = @Content(schema = @Schema(implementation = PostMethodResponsePayload.class))),
            @ApiResponse(responseCode = "400", description = "bad request operation", content = @Content(schema = @Schema(implementation = ResponsePayload.class)))
    })
    ResponseEntity<ResponsePayload> httpMethodPost(@RequestBody @Validated PostMethodRequestPayload payload, BindingResult error) throws CustomRunTimeException;

    @Operation(summary = "Put Request Template", description = "HttpMethod.Put Method를 이용한 HTTP Request")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = PostMethodResponsePayload.class))),
            @ApiResponse(responseCode = "201", description = "created operation", content = @Content(schema = @Schema(implementation = PostMethodResponsePayload.class))),
            @ApiResponse(responseCode = "400", description = "bad request operation", content = @Content(schema = @Schema(implementation = ResponsePayload.class)))
    })
    ResponseEntity<ResponsePayload> httpMethodPut(@RequestBody @Validated PostMethodRequestPayload payload, BindingResult error) throws CustomRunTimeException;

    @Operation(summary = "Delete Request Template", description = "HttpMethod.Delete Method를 이용한 HTTP Request")
    @Parameters({
            @Parameter(name = "tempString", description = "TestPostRequestPayload 의 tempString Field", required = true)
    })
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = PostMethodResponsePayload.class))),
            @ApiResponse(responseCode = "400", description = "bad request operation", content = @Content(schema = @Schema(implementation = ResponsePayload.class)))
    })
    ResponseEntity<ResponsePayload> httpMethodDelete(@ParameterObject @RequestBody @Validated PostMethodRequestPayload payload, BindingResult error) throws CustomRunTimeException;
}

• Controller 구현체에 Swgger Annotation을 작성하게 되면 Controller 기능에 있는 Source들과 섞여서 가독성이 너무 떨어지기에 Interface로 만든 뒤 Interface에서는 Swagger Annotation만 선언하고, 해당 Interface를 상속받은 Controller 구현체에서 API Annotation & Source를 작성하도록 하면 처음에는 조금 귀찮지만 나중에 훨씬 편히라게 관리가 가능하다.
• Controller Interface에서 사용된 Swaager Annotation들에 대해서는 다음 글에서 자세하게 알아보도록 하자

📝 Swagger 페이지 생성

• 위와 같이 스웨거 페이지가 생성된다.

📌 마무리

Swagger에 대해서 오늘 기본적인 설정 방법과 결과에 대해서 기록하였다.
다음에는 Swagger의 Anntation에 대해서 자세히 기록하려고 한다.
백엔드와 프론트엔드의 협업을 위해서는 반드시 필요한 프레임워크라고 생각한다.