Swagger

1.스웨거(Swagger)란?

스웨거는 Open Api Specification(OAS)를 위한 프레임워크다. url 리스트를 html화면으로 문서화 및 테스트할 수 있는 라이브러리. 즉, 상대 개발자한테 스웨거만 전달해주면 API path, Request, Response값 및 제약 등을 한번에 알려줄 수 있음

OAS : RESTful 웹서비스를 양식에 맞게 API스펙을 json과 yaml 형식으로 표현한다. 즉, 추가적인 설명없이 서비스를 이해할 수 있게 됨.

스웨거 기능

• swagger-editor : API 문서화
• swagger-codegen : SDK 생성으로 빌드 프로세스 간소화
• swagger-ui : API 시각화
• swagger-inspector : API 시각화 및 테스트
• swagger-hub : API 공유

2.설정(스프링 스타터 프로젝트 기준)

• (Maven)pom.xml에서 dependency 추가

<!-- swagger 설정 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>	

• application.properties

spring.mvc.pathmatch.matching-strategy=ant-path-matcher 추가

해당 설정은 스프링 버전과 dependency로 불러온 스웨거 버전의 호환문제가 생길 수 있으므로 해주는 설정이다.

3.구성

• Docket(DocumentationType.SWAGGER_2) : swagger 설정 필수로 Bean으로 등록해줘야 한다, 파라미터는 swagger 버전에 맞춰 설정해준다
  • ignoredParameterType(ApiIgnore.class) : ApiIgnore어노테이션을 적용한 클래스를 안보이게 하겠다는 설정이다
  • apiInfo(사용자정의 메서드) : swagger-ui로 열린 http문서상 헤더, 설명 등을 사용자정의 메서드로 개발하고 이를 호출한다
    • 해당 사용자정의 메서드 구성
    • ApiInfoBuiler() : 내용빌드시작
    • title() : 제목설정
    • description() : 부연설명설정
    • license().licenseUrl() : 라이센서, 라이센서 url 설정
    • version() : 버전 설정
    • build() : 내용빌드마무리
  • apis(RequestHandlerSelectors.basePackages(“컨트롤러 패키지명”)) : 컨트롤러 존재하는 패키지 등록
  • useDefaultResponseMessage(boolean) : 설정되지 않아도 대표적인 문서상태에 대한 표현 표시하느냐 마느냐
• @ApiIgnore :
• @ApiModel :
  • value :
  • description :
• @ApiModelProperty :
  • example :
• @ApiOperation :
  • value :
  • notes :
• @ApiResponses : 200,404,500 등등의 상황에 따라 표시할 내용
  • @ApiResponse :
    • code :
    • message :

html로 확인

localhost:port번호/swagger-ui.html 접속!!!

스프링부트에서 스웨거 오류날때!!

스프링부트 버전에 따라 오류가 생기는 경우가 있다고 한다!
application.properties에 spring.mvc.pathmatch.matching-strategy=ant-path-matcher를 추가시켜줘야함!