Swagger란?

스웨거(Swagger)는 개발자가 REST API 서비스를 설계, 빌드, 문서화할 수 있도록 도와주는 오픈 소스 소프트웨어 프레임워크이다.

---

사용 이유?

프로젝트를 진행하다 보면 API 문서를 만들어야 하는 경우가 종종 있다.
그런데 그때마다 API 문서를 만들면서 개발도 하려니 생각보다 시간이 많이 걸렸다.
그래서 개발에 집중하면서 API 문서를 자동하할 수 있게 해주는 Swagger라는 라이브러리를 알게 되어 사용하게 되었다.

---

Swagger 초기 세팅

pom.xml 의존성 추가

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

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

SwaggerConfig.java

SWagger 기본 설정을 위한 Config 클래스 생성

@EnableSwagger2
@Configuration
public class SwaggerConfig {

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


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


	public ApiInfo getApiInfo() {
		return new ApiInfo(
				"Service REST API Documentation",
				"REST Api Documentation",
				"1.0",
				"localhost:8080",
				new Contact("unhak","https://velog.io/@unknown89","chldnsgkr7@gmail.com"),
				"Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0",
				new ArrayList<VendorExtension>());
	}
}

• @EnableSwagger2
  Swagger2 버전을 활성화 하겠다는 어노테이션이다.
• Docket
  Swagger 설정의 핵심이 되는 Bean이다.
  1. useDefaultResponseMessages()
  : false로 설정하면, swagger에서 제공해주는 응답코드 (200,401,403,404)에 대한 기본 메시지를 제거해준다.
  2. select()
  : ApiSelectorBuilder를 생성하여 apis()와 paths()를 사용할 수 있게 해준다.
  3. apiInfo()
  : 제목, 설명 등 문서에 대한 정보들을 설정하기 위해 호출한다.
  4. apis()
  : api 스펙이 작성되어 있는 패키지를 지정한다.
  5. paths()
  : apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화한다.
  PathSelectors.any()로 설정하면 패키지 안에 모든 API를 한 번에 볼 수 있다.

---

Swagger 사용법

SwaggerController.java

@Api(value = "SwaggerController")
@RequestMapping("/v1/api")
@RestController
public class SwaggerController {

    @ApiOperation(value = "Swagger Test", notes = "Test Notes")
    @GetMapping(value = "/test")
    public Map<String, String> selectOneBoard(@ApiParam(name = "first param", value = "first value", required = true) String input) {
        Map<String, String> result = new HashMap<>();
        result.put("author", "unhak");
        result.put("content", "V1 API 내용");
        return result;
    }
}

• @Api
  해당 클래스가 Swagger 리소스라는 것을 명시해준다.
  1. value : 사용자 지정 이름을 붙일 수 있다. tags 사용시 무시된다.
  2. tags : 사용하여 여러 개의 태그를 정의할 수도 있다.
• @ApiOperation
  한 개의 Operation을 선언한다.
  1. value : API에 대한 요약을 작성한다. 제대로 표시되려면 120자 이하여야 한다.
  2. notes : API에 대한 자세한 설명을 작성한다.
• @ApiParam
  1. name : 파라미터 이름을 작성한다.
  2. value : 파라미터 설명을 작성한다.
  3. required : 필수 파라미터이면 true, 아니면 false를 작성한다.
  

---

결과 화면

---

참고 자료

Docket Bean을 설정 방법
Swagger 공식문서