[Swagger-SpringMVC] Swagger-SpringMVC with Swagger-UI (REST API auto documentation)

개발자에게 문서 작성이란 참 귀찮은 일이다.

하지만, 뭔가 프로토콜을 구현하다보면 문서 작성은 필수적인 일이다.

 

Swagger는 이런 귀찮은 프로토콜 문서 작성을 자동화 시켜준다.

 

Swagger 자체부터 파고들면, 어려웠겠지만 Spring MVC전용으로 누군가 커스터마이징해서 올려둔 게 있어서

이걸 적용해 보았다. 

 

[Swagger-SpringMVC 설정 (https://github.com/martypitt/swagger-springmvc)] 

1. Maven에 의존성을 추가해준다.  

 - 현재 Swagger-SpringMVC의 경우 가장 최신버전이 0.9버전인데, Maven Central Repositories에서는 0.88버전인가까지밖에 올라와 있지 않다.

 - 0.9버전을 사용하기 위해, Repository를 따로 등록해준다.

<repository>
          <id>jcenter-release</id>
          <name>jcenter</name>
          <url>http://oss.jfrog.org/artifactory/oss-release-local</url>
</repository>
<dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>0.9.0</version>
</dependency>

 

2. Jackson을 사용하고 있지 않다면, Jackson도 의존성에 추가해준다. (Swagger-SpringMVC는 내부적으로 JacksonMessageConverter를 사용하기 때문) - 현재 가장 최신버전은 2.4.3이다. 

<dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.4.3</version>
 </dependency>
 <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.4.3</version>
 </dependency> 

 

3. 2번에 설명한 것과 같이 JacksonMessageConverter를 Spring Config에 추가해주어야 한다.

 - Java Config기준으로 WebMvcConfigurerAdapter를 상속받은 클래스(Servlet설정)에서  

configureMessageConverters Method를 override해서 처리한다. 

 

4. Spring Servlet설정(3번에 명시한 WebMvcConfigurerAdapter) 클래스에 @EnableSwagger를 추가해준다.

 - 여기서 주의할 점은, ComponentScan등으로 Controller 어노테이션 등 문서화할 REST API들을 찾아 Bean으로 만들어주는 작업이 선행되어 있어야 한다는 것

 

5. 확인은 로컬 톰캣 기본 설정 기준으로 http://localhost:8080/{어플리케이션ROOT Path}/api-docs에서 한다.

 

[Swagger UI 설정 (https://github.com/wordnik/swagger-ui) - GitHub에서 생략되어 있는 설명들이 너무나도 많다.-_-]

1. git bash등을 이용해서 https://github.com/wordnik/swagger-ui.git를 clone으로 로컬에 땡겨온 후에, 웹 프로젝트에 추가해준다.

 - 땡겨오게되면, dist라는 폴더만 있는데 그 안에 있는 내용들만 WEB-INF/views/swagger-ui 폴더를 생성하여 넣어주도록 한다.

 

2. Spring Servlet설정에서 InternalResourceViewResolver를 생성해주고, 리소스 경로를 루트에서 사용할 수 있도록 설정해준다.  

(가장 중요한 설정이며, 뭔가 잘 안되면 무조건 이 설정에서 경로가 잘못지정된 것이다. /를 넣느냐 마느냐가 매우 중요한 역할을 함..--) 

@Bean
public InternalResourceViewResolver getInternalResourceViewResolver() {
        InternalResourceViewResolver resolver = new InternalResourceViewResolver();
        resolver.setPrefix("/WEB-INF/views/");
        resolver.setSuffix(".jsp");
        return resolver;
}

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("**")
                .addResourceLocations("/WEB-INF/views/swagger-ui/")
                .setCachePeriod(0);
}

@Override
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
}

 

3. WEB-INF/views/swagger-ui/index.html파일을 index.jsp로 바꾸어준다. 

 - 확장자만 바꾸면 안되고, jsp상단에 항상 포함되어 있는,  

<%@ page language="java" contentType="text/html; charset=EUC-KR" pageEncoding="EUC-KR"%> 도 같이 넣어준다.

 

4. ModelAndView형식의 컨트롤러를 하나 만들어서, index.jsp파일을 열도록 해준다.

@RequestMapping(value = "/ui")
public ModelAndView ui(ModelAndView mav) {
        mav.setViewName("/swagger-ui/index");
        return mav;
}

 

5. 확인

 - http://localhost:8080/{Root Path}/ui

 

 

세팅은 여기까지가 완료이고, 더 연구해 보아야할 것들을 정리해보면..

1. UI상에 Parameter와 Response들이 표시가 되는데, @RequestParam이나 @RequestBody등을 사용하지 않고

Pojo로 받는 경우에는 해당 Pojo의 클래스명만 나오고, 클래스의 내부 variable들은 보이지 않는다.

 

2. 파라미터를 입력할 수 있는 Text Box에 1번처럼 @RequestParam, @RequestBody를 사용하지 않고, Pojo인 경우

아무것도 없는 비어있는 Text Box가 나온다. (1번이 해결되면 같이 해결될 문제인 것 같음)

 

 

현재 개발중인 어플리케이션이 파라미터는 Pojo로 받고, 리턴은 Map으로 하기 때문에,

뭔가 커스터마이징해야 원하는대로 사용할 수 있을 것 같다.  

사용할 수 있는건, 현재 구현되어 있는 API가 어떤게 있다라는 정도...

 

고생한 거에 비해 소득이 별로 없으니, 커스터마이징을 해봐야겠다.  

 

[커스터마이징 결과]

UI에 보이는 Parameter DataType부분을 Pojo에 선언된 변수들을 Reflection으로 열어서, Json String으로 만들어 뿌려주는 것은 성공

하지만, 이 작업에는 SwaggerSpringMvcPlugin의 옵션중 customAnnotationReaders옵션을 이용하여

Reader를 직접 구현하여 넣어주어야 하며, 기존에 등록되어 있던 Reader가 고스란히 동작하는 바람에, 두번 처리가 되어

UI상에도 두줄로 표시되고 있었다.. ㅡㅡ;;  

 

RequestParam이랑 RequestBody쓰면 암것도 안건드리고, 그냥되는건데

왜 Json문자열 앞에 파라미터명이 있고, 그 파라미터로 Json통 문자열이 들어와버리니 참 골치아픔..

 

결론은.. 여기에 맞게 사용하려면 Reader를 제거할 수 있는 옵션이 나오길 기다려야되는듯;;;