[KNU_30 개발일기] 낡은 웹페이지의 업데이트 시작 - Swagger를 활용한 API 개발 명세 자동화

1. 개요

 

 약 1년전 KNU_30이라는 강남대학교 30주년 이벤트 페이지를 개발한 경험이 있다. 학교에서 서버를 지원해주는 사업이었기 때문에 신나게 서버를 가지고 논 기억이 난다. 단순한 일회성 페이지로 개발되었지만, 프론트 개발을 주도한 친구가 괜찮은 UI를 개발했기 때문에, 동아리도 소개하고 영상들도 첨부하는 페이지가 되었다. 오랜만에 들어가보니 아직도 서버는 구동중이고 방문 로그는 쌓여있는걸 확인할 수 있었다.

 

 서버 한 대가 아깝다는 생각이 들었다. 그래서 관리자 페이지를 만들어 기본적인 데이터 CRUD를 개발하고 싶었다. 교수님을 따로 찾아 봬었다. 팀을 모집하고 장기적으로 개발할 계획이다. 오늘은 그 개발의 첫 단계, Swagger를 활용한 API 개발 명세 자동화이다. 사실 별거 없지만, 그래도 나랑 같은 고민을 할 수 있는 사람들을 위해 글을 남겨본다.

---

---

2. 본론

 

 모든 백앤드 개발은 API 명세가 필요하다. 어떤 API가 어떤 로직을 수행하는지를 명세해야 수훨한 팀개발을 진행 할 수 있다. 사실 나도 책에서 읽은 내용이지만, 실제로 API 명세가 있으니 나도 햇갈리던 많은 API들을 한 눈에 볼 수 있어서 좋았다. 중요한점은 나는 이런 API 명세를 내 아이패드에 수기로 작성했다는 것이다. 진짜 미치고 환장할 노릇이지만, 학부수준에서는 괜찮게 사용했다. 오늘은 이 낡은 방식을 Swagger를 통해 해결해보고자 한다.

 

- Swagger란?

 

 API는 개발 과정에서 계속 변경된다. 그렇기에 API 명세도 변경된다. 지속적인 업데이트를 필요로하기에 이런 API 명세 작성 과정은 번거롭다. 그래서 Swagger라는 오픈소스가 등장했다.

---

Swagger 공식 홈페이지: https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

Swagger 설명: https://ko.wikipedia.org/wiki/%EC%8A%A4%EC%9B%A8%EA%B1%B0_(%EC%86%8C%ED%94%84%ED%8A%B8%EC%9B%A8%EC%96%B4) 

스웨거 (소프트웨어) - 위키백과, 우리 모두의 백과사전

---

 자신이 controller에 작성한 API들을 편하게 보여준다고 생각하면 된다. Spring Rest Docs를 활용한 방식도 있지만 이 글에서는 Swagger를 다루고자 한다. 일단 설정이 매우 쉽기 때문이다.

 

- Swagger 설정

 

 Swagger를 자신의 페이지 혹은 애플리케이션에 설정하는 방법은 크게 두 단계로 나뉜다.

 

1. pom.xml에 의존성 추가

2. swagger 설정 코드 작성

 

 pom.xml에 추가한 의존성은 다음과 같다.

 

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

 

 지금은 swagger3이 출시된 것으로 알고 있지만, 나는 2를 사용했다. 이유는 그냥 무서웠기 때문이다. 최신버젼은 나에게 항상 무섭다... ㅠㅠ

 

 swagger는 설정코드를 Java의 Class형태로 작성하고 이 Class가 Swagger의 설정코드라는 것을 어노테이션으로 명시한다. swagger의 설정 class의 위치는 사람마다 다르지만 나같은 경우는 가장 기본적인 경로 밑에 config파일을 만들고 그 밑에 class를 생성하였다. groupID는 com.kang, artifactId는 knu_30이기에 경로는 com.kang.knu_30.config이고 파일 명은 Class명은 SwaggerConfiguration.java이다.

 

-  SwaggerConfiguration.java

package com.kang.knu_30.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kang.knu_30"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot Open API Test with swagger")
                .description("description session")
                .version("1.0.0")
                .build();
    }

}

 

apiInfo 메소드를 보면 지금 생성하는 Swagger 명세에 관련된 설명을 추가한다. 다음과 같이 설정하면, swagger의 main page는 다음과 같이 나온다.

---

---

 Docket 메소드에서는 명세페이지에 대한 간단한 설정을 한다. apis메소드에는 basePackage를 설정한다. 최종적인 페이지는 다음과 같다.

---

---

3. 결어

 

 내가 원하는 백앤드 개발의 첫 단계를 완료했다. Swagger를 사용한다면, api 개발 명세는 신경쓰지 않아도 될 것 같아 기쁘다. 조금씩 최신 기술을 추가해 서비스를 키워나갔으면 좋겠다.