swagger 연동을 통한 자동 API 문서 생성하기

---

• [ 배경 ]
  • 토이 프로젝트인 중고거래 시스템을 개발하면서 특정 API가 어떤 파라미터들을 가지고 각 파라미터의 자료형과 내용이 무엇인지를 알려주는 문서 작업이 필요했습니다.
  • Spring 환경에서 문서화를 해주는 라이브러리는 구글링 결과 Spring Rest Doc와 Swagger가 있습니다.
    각각 라이브러리의 중요 특징을 비교해보자면 아래와 같습니다.

• 우선 Redst Docs와 Swagger는 성격이 많이 다릅니다. Swagger는 RESTful 문서에 대한 명세보다는 Postman Tool처럼 특정 API를 쉽게 호출해볼 수 있는 것에 초점이 맞춰져 있습니다.  반면에 Spring Rest Docs는 깔끔 명료한 문서를 만들 수 있습니다. 그래서 문서 제공용으로는 Spring Rest Docs가 좀더 나을 수 있습니다.
  
  
• Swagger는 RESTfulAPI에 대한 명세를 어노테이션 방법으로 제공해주지만 다음과 같은 단점도 있습니다.
  • 실제 코드에 영향을 미치지 않지만 지속해서 추가됨으로써 실제 코드보다 문서 명세에 대한 코드가 더 길어져 전체적인 가독성이 떨어집니다.
    
    
• 하지만 중고거래 사이트 경우 백엔드 시스템으로 간단한 문서화와 같이 테스트해볼 수 있는 Front UI도 필요해서 Swagger 라이브러리를 사용하기로 하였습니다.
  
  
• 추후 코드 유지보수시 문서 동기화 측면이나 가독성 측면에서 문제 발생 시 Spring Rest Docs 사용도 고려할 예정입니다.

 

---

• [ 과정 ]
  • 중고거래 프로젝트에 적용하는 과정에 대해 설명드리겠습니다.
    
    
  • 우선 pom.xml 파일에 springfox-swagger2, springfox-swagger-ui 의존성을 각각 추가합니다.
    
    
  • springfox-swagger2는 JSON API 문서를 제공해주는 라이브러리입니다.
    
    
  • springfox-swagger-ui는 JSON API 문서에 모든 콘텐츠는 다음 형식을 사용하는 URL 인 webjar 규칙을 제공합니다. (http://IP:port/swagger-ui.html)

 

• 의존성 추가 시 <version> 태그에 버전을 명시하지 않으면 Spring-boot 환경이더라도 동작하지 않았습니다.

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

view raw pom.xml hosted with ❤ by GitHub

• SwaggerConfig.java 파일에서 현재 애플리케이션의 문서명, 추가설명, 버전, license 명, license url 등을 ApiInfo에 설정합니다.
  
  
• io.springfox:springfox-spring-web:2.6.1 의존성에 있고 Swagger 설정의 핵심이 되는 Bean인
  Docket 클래스를 인스턴스로 생성할 때 ApiInfo 에 설정한 정보를 파라미터에 설정합니다.
  그 외에 basePackage, PathSelectors, DefaultResponseMessages 등을 설정고 빌드합니다.
  

	@Configuration
	@EnableSwagger2
	public class SwaggerConfig {
	@Bean
	public Docket swaggerApi() {
	return new Docket(DocumentationType.SWAGGER_2).apiInfo(swaggerInfo()).select()
	.apis(RequestHandlerSelectors.basePackage("com.market.server.controller"))
	.paths(PathSelectors.any())
	.build()
	.useDefaultResponseMessages(false); // 기본으로 세팅되는 200,401,403,404 메시지를 표시 하지 않음
	}
	private ApiInfo swaggerInfo() {
	/*
	API 문서화 및 테스트를 가능케 해주는 Springfox
	return new ApiInfoBuilder()
	.title("Api Documentation")
	.description("Api Documentation")
	.version("1.0")
	.license("Apache License Version 2.0")
	.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
	.build();
	아레와 같이 문서에 대한 문서명, 추가설명, 버전, license 명, license url 등을 설정 하여 API에 대한 정보를 나타내 줍니다.
	*/
	return new ApiInfoBuilder().title("Spring API Documentation")
	.description("앱 개발시 사용되는 서버 API에 대한 연동 문서입니다").build();
	}
	}

view raw SwaggerConfig.java hosted with ❤ by GitHub

• http://IP:port/swagger-ui.htmlURL에 접근 시 Swagger-ui.html 에서 정상 작동하는 것을 볼 수 있습니다.
  

 

---

• [ 결과 ]
  • 아래와 같이 중고거래 물품의 검색 API가 어떤 파라미터들을 가지고 각 파라미터의 자료형과 내용이 무엇인지 알 수 있게 되었습니다.

---

• [ 성과 ]
  • REST API 설계를 swagger 라이브러리를 활용하여 간단한 설정으로 API Document가 자동 생성되게 하였습니다.
    결과적으로 문서 내용에 대한 추가 작업을 하지 않게 되어 개발 생산성이 향상되었습니다.

---

• used-market-server 중고거래 프로젝트 코드는 아래에서 확인하실 수 있습니다.
  • github.com/junshock5/used-market-server.git

junshock5/used-market-server

• [ 참고 ] 
  • https://springfox.github.io/springfox/docs/current/
  • https://swagger.io/
  • https://woowabros.github.io/experience/2018/12/28/spring-rest-docs.html
  • https://smujihoon.tistory.com/218