스웨거 (swagger) Spring 사용법

 

 

• 스웨거란?

REST API의 문서화를 위해 사용하는 것

간단한 설정으로 프로젝트의 API목록을 웹에서 확인 및 테스트 가능하게 하는 라이브러리이다.

 

• 사용하는 이유?

프로젝트 개발 및 유지보수시 API의 규격을 정의한 문서는 꼭 필요하다.

만약 API의 규격에 대한 문서가 없다면 API를 확인할 때 시간 낭비가 심하고, 테스트할 때도 코드를 일일이 분석해야한다.

 

하지만, 문서화 조차도 시간이 많이 드는 작업임에는 변함이 없다.

API를 추가, 변경할 때마다 일일이 문서화해야 할테니 번거롭다.

이런 문제를 해결하기 위해 swagger를 사용한다.

 

• 사용법

  [pom.xml]

<!-- Springfox-swagger2 -->

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.4.0</version>

</dependency>

 

<!-- springfox-swagger-ui -->

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.4.0</version>

</dependency>

 

---

[servlet-context.xml]

 

<beans:bean id="swagger2Config"

class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration">

</beans:bean>

 

<default-servlet-handler />

<resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"></resources>

<resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"></resources>

 

 

 

• 결과

 

 

swagger url

 

 

 

 

 

• 스웨거에 설명 추가하기

 

 

컨트롤러나 메서드 혹은 파라미터에 추가적인 설명을 추가하기 위해 Swagger에서 제공하는 어노테이션을 사용하자.

컨트롤러에 @Api("내용")
메소드에 @ApiOperation(value="내용")

(참고로 파라미터는 @ApiImplicitParams )

 

들을 각각 추가한다.

 

• 결과

 

 

swagger-ui

 

• API 실행

'Jew8969' 라는 아이디는 DB에 없는 데이터로서 '사용 가능합니다' 라는 결과값 확인

 

 

 

 

 

'jew8960'이라는 아이디는 DB에 있는 데이터로서 '이미 해당 아이디가 있다' 는 결과값 확인

 

 

 

 

 

 

withjew.tistory.com/6