[Spring]Swagger

신동혁·2022년 8월 12일
0

Spring

목록 보기
4/4

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를 추가시켜줘야함!

profile
개발취준생

0개의 댓글