spring boot에서 swagger 설정 및 사용

아래 설정보다는 

http://springboot.tistory.com/24 <<< 여기를 참고하는걸 추천합니다.

환경

• Spring boot 1.2.5.REALESE
• Maven
• swagger-springmvc 1.0.2
• swagger-ui

소개

  최근 Restful API를 많이 사용하는데, client와 협업하기 위해서 API 문서가 중요한데, API를 개발하며 수정 사항도 많이 발생하기 때문에 API가 수정되면 문서를 일일히 수정하기는 많이 번거롭다. 때문에 API 문서를 자동화하는게 좋은데 사용해보진 않았지만 IODocs와 swagger를 많이 사용한다. 이번 포스팅에서는 swagger를 설정하고 간단하게 사용하는 방법에 대한 내용이다.

Swagger Config

  swagger를 스프링에서 사용하기 위해서 간단한 설정이 필요하다. 먼저 swagger-springmvc dependency를 먼저 추가 해야한다.

        
            com.mangofactory
            swagger-springmvc
            1.0.2
        

다음은 swagger javaConfig 부분이다.

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableSwagger
public class SwaggerConfig {

    @Autowired private SpringSwaggerConfig springSwaggerConfig;

    @Bean
    public SwaggerSpringMvcPlugin swaggerSpringMvcPlugin() {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(new ApiInfo("spring-boot-swagger", null, null, null, null, null))
                .useDefaultResponseMessages(false)
                .includePatterns("/*");
    }
}

swagger-springmvc dependency를 추가하면 자동으로 SpringSwaggerConfig 클래스가 자동으로 Bean으로 등록 되므로 직접 Bean으로 설정할 필요 없다. 단지 SwaggerSpringMvcPlugin만 Bean으로 등록하면 끝난다.

Controller (Swagger Annotation)

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiResponse;
import com.wordnik.swagger.annotations.ApiResponses;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;

@Api(value = "HomeController", description = "swagger test",basePath = "/")
@RestController
public class HomeController {

    @ApiOperation(value = "test swagger", notes = "test swagger")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "success request")
    })
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public ResponseEntity<?> hello() {
        Map<String, String> datas = new HashMap<>();
        datas.put("hello", "spring");

        return ResponseEntity.ok(datas);
    }
}

@Api로 시작하는 애노테이션 모두 Swagger에서 지원하는데 이는 swagger-ui를 통해 url별 정보를 보여주기 위한 애노테이션이다.

위 Controller는 아래와 같이 간단하게 json 형태로 respnose하는 Controller다.

swagger-ui

  제일 중요한 부분이라고 할 수 있다. swagger를 사용하는 목적 자체가 자동 문서화이기 때문에 ui 설정을 해야한다.

• resources/static 밑에 다운받은 swagger-ui를 복사해 넣는다.

• dist 폴더를 swagger로 이름을 변경한다.

모든 설정이 끝났다. 테스트 하기 위해 http://localhost:8080/swagger/index.html 로 접속하면 아래와 같이 ui가 뜨면 성공이다. 아무것도 보이지 않는다면 show/hide 버튼을 눌러 정보를 펼친다.