[Spring] spring 에 swagger 적용하기

* 환경

Springframework 4.3.16.RELEASE

Spring security 4.2.5.RELEASE

egovframework 3.8.0

 

 

이전에 백엔드 작업을 하며 Postman을 사용하다가 좀 더 API 문서적으로 활용하고 싶어서 스웨거를 도입했다. 

실행 과정을 기록해둔다. 

 

 

---

 

 

 

1️⃣ pom.xml

<properties>
	<!-- swagger -->
	<swagger.version>2.9.2</swagger.version>
</properties>

...

<!-- springfox-swagger2 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>${swagger.version}</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>${swagger.version}</version>
</dependency>

Maven build 진행

 

 

 

2️⃣ action-servlet.xml 

<!-- swagger -->
<beans:bean id="swagger2Config" class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration" />
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html" />
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**" />

빈 생성

 

 

 

3️⃣ security-context.xml

<!-- swagger -->
<sec:intercept-url pattern="/swagger-ui.html/**" access="isAnonymous()" />
<sec:intercept-url pattern="/configuration/**" access="isAnonymous()" />
<sec:intercept-url pattern="/swagger-resources/**" access="isAnonymous()" />
<sec:intercept-url pattern="/v2/api-docs" access="isAnonymous()" />
<sec:intercept-url pattern="/webjars/**" access="isAnonymous()" />
<sec:intercept-url pattern="/webjars/springfox-swagger-ui/*.{js,css}" access="isAnonymous()" />

시큐리티에서 권한 제한 없이 swagger 페이지 설정

 

 

 

4️⃣ SwaggerConfig.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;


@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {

    @Bean
    public Docket customImplementation() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)  // 기존적인 응답메시지 미사용
                .globalResponseMessage(RequestMethod.POST, getArrayList()) // 정의한 응답메시지 사용
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("egovframework"))
                .paths(PathSelectors.any())
                .build();
    }

    // 선택항목(Swagger UI에서 보여지는 정보)
    public ApiInfo getApiInfo() {
        return new ApiInfo("마이시스템 REST API Documentation",
                "REST Api Documentation",
                "1.0",
                "localhost:8080",
                new Contact("myhome","http://myhome.co.kr","test@test.email"),
                            "마이시스템", "http://myhome.co.kr",
                new ArrayList<VendorExtension>());
    }

    
    private ArrayList<ResponseMessage> getArrayList() {
        ArrayList<ResponseMessage> lists = new ArrayList<ResponseMessage>();
        lists.add(new ResponseMessageBuilder().code(500).message("500 ERROR").build());
        lists.add(new ResponseMessageBuilder().code(403).message("403 ERROR").build());
        lists.add(new ResponseMessageBuilder().code(401).message("401 ERROR").build());
        return lists;
    }
}

스웨거 관련 커스터마이징 

 

 

 

5️⃣ Controller.java

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import lombok.AllArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.ModelAndView;

@RestController
@AllArgsConstructor
@RequestMapping("/board")
@Api(value = "BoardController", tags = "게시판")
public class BoardController {
	
	@GetMapping(value="/search")
	@ApiOperation(value = "검색", notes = "search")	// 메소드에 대한 설명
	@ApiImplicitParam(name="title", value="글제목")	// parameter 설명
	public ResponseEntity search(@RequestParam String title) throws Exception {
		List<?> resultList;
		String message = ResponseMessage.SUCCESS;
		try {			
			resultList = 검색 api();

		} catch (Exception ex) {
			logger.error("ErrMsg {} : " + ex.getMessage(), ex);
			return new ResponseEntity(DefaultResponse.res(
					StatusCode.INTERNAL_SERVER_ERROR,
					ResponseMessage.INTERNAL_SERVER_ERROR, null), HttpStatus.OK);
		}
		return new ResponseEntity(DefaultResponse.res(StatusCode.SUCCESS, message, resultList), HttpStatus.OK);
	}


	@GetMapping
	@ApiOperation(value = "상세조회", notes = "view")
	@ApiImplicitParams({@ApiImplicitParam(name="offset", value="현재 페이지 번호"),
    				@ApiImplicitParam(name="no", value="글번호")})	// 다중 parameter 처리시
	public ModelAndView paging( @RequestParam(required=false) String no,
    					@RequestParam(required=false) String offset){

		ModelAndView model = new ModelAndView("board/view");
		model.addObject("no", offset);
		model.addObject("no", no);

		return model;
	}

}

 

서버 실행 후, http://localhost:8080/swagger-ui.html 으로 접속하면 화면 확인이 가능하다! 

 

 

 

 

 

 

[참고]

 

https://twofootdog.github.io/Spring-Spring-MVC%EC%97%90-Swagger-%EC%A0%81%EC%9A%A9%ED%95%98%EA%B8%B0/

[Spring]Spring MVC에 Swagger 적용하기 | 두발로걷는개

https://blogdeveloperspot.blogspot.com/2018/04/maven-spring-swagger2-guava-error.html

maven 프로젝트 Spring swagger2 적용시 org.springframework.beans.factory.BeanCreationException: Error creating bean with n