Swagger 사용해보기(java.lang.NoSuchMethodError: 'boolean io.swagger.v3.oas.models.media.Schema.getExampleSetFlag()해결)

🍃 오늘은 Swagger에 대해 알아보자 

😀 Swagger란?

API 문서화와 테스트를 지원하는 오픈 소스 프레임워크로, RESTful 웹 서비스의 설계, 빌드, 문서화, 소비자 테스트 등을 더 쉽게 만들어주는 도구이다. Swagger는 RESTful API의 개발 및 관리를 단순화하고 문서화를 자동화하는 데 도움이 된다.

😀 Swagger의 주요 기능과 개념

1) API 문서화

Swagger를 사용하면 API 엔드포인트, 요청 및 응답 모델, 파라미터, HTTP 메서드, 예제 요청 및 응답 등 API에 대한 자세한 문서를 자동으로 생성할 수 있다. 이 문서화는 Swagger UI를 통해 사용자 친화적인 HTML 또는 JSON 형식으로 제공된다.

 

2) API 디자인

Swagger를 사용하여 API의 설계와 스키마를 정의할 수 있으며, 이를 기반으로 코드를 자동으로 생성할 수 있다.

 

3) API 테스트

Swagger UI를 통해 API를 테스트할 수 있다. 이를 통해 API가 예상대로 동작하는지 확인하고 디버깅할 수 있다.

 

4) 코드 생성

Swagger 스키마를 기반으로 클라이언트 및 서버 코드를 자동으로 생성할 수 있다. 이는 서버 및 클라이언트 개발자 간의 통합을 용이하게 한다.

5) 다양한 언어 지원

Swagger는 다양한 프로그래밍 언어 및 플랫폼에서 사용할 수 있으며, Swagger 도구 세트는 Java, JavaScript, Python, Go, .NET, Ruby 및 다른 언어에서 사용 가능하다.

 

🍃 Swagger 사용해보기

1. 의존성 추가

implementation "io.springfox:springfox-boot-starter:3.0.0"
implementation "io.springfox:springfox-swagger-ui:3.0.0"

 

2. swaggerConfig 작성

	@Configuration
    @EnableSwagger2
    public class SwaggerConfig {

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

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("test")
                    .description("API 문서입니다.")
                    .version("1.0")
                    .build();
        }
    }

 

3.  사용할 API 써주기

API 기능 명세를 위해 클래스나 메소드 위에 어노테이션을 추가하여 쉽게 정의할 수 있다.

어노테이션	설명
@Api	클래스를 스웨거의 리소스로 표시 · 해당 클래스가 Swagger 리소스라는 것을 명시 · 클래스 위에 선언
@ApiOperation	특정 경로의 오퍼레이션 HTTP 메소드 설명 · 한 개의 Operation을 선언 · 메소드 위에 선언
@ApiParam	오퍼레이션 파라미터에 메타 데이터 설명 · 파라미터에 대한 정보 명시 · 메소드안에 파라미터 위에 선언
@ApiResponse	오퍼레이션의 응답 지정
@ApiModelProperty	모델의 속성 데이터를 설명 · Dto 클래스안에 프로퍼티위에 선언
@ApiImplicitParam	메소드 단위의 오퍼레이션 파라미터 설명 · 파라미터에 대한 정보 명시 · 메소드 위에 선언
@ApiImplicitParams	메소드 단위의 오퍼레이션 파라미터 여러개 설명 · 파라미터에 대한 정보 명시 · 메소드 위에 선언

​

Swagger 설정 정보 클래스 생성

· Docket 클래스를 정의한다.

메소드	설명
useDefaultResponseMessages()	false로 설정하면 Swagger에서 제공해주는 응답코드(200, 401, 403, 404)에 대한 기본 메시지를 제거해준다.
groupName()	Docket Bean이 한 개일 경우 생략해도 상관없으나, 둘 이상일 경우 충돌을 방지해야 하므로 설정해줘야 한다.
select()	ApiSelectorBuilder를 생성하여 apis()와 paths()를 사용할 수 있게 해준다.
apis()	api 스펙이 작성되어 있는 패키지를 지정한다. 컨트롤러가 존재하는 패키지를 basepackage로 지정하여 해당 패키지에 존재하는 API를 문서화 한다. RequestHandlerSelectors.any()로 설정하면 모든 패키지를 basepackage로 지정하여 API를 문서화 한다.
paths()	apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화한다. PathSelectors.any()로 설정하면 패키지 안에 모든 API를 한 번에 볼 수 있다.
apiInfo()	제목, 설명 등 문서에 대한 정보들을 설정하기 위해 호출한다.

출처 : https://m.blog.naver.com/hj_kim97/222652876898

[Spring]Spring Swagger 사용법 정리(API 문서 자동화하기)

 

예시

@PostMapping("/write")
@ApiOperation(value="BoardWrite", notes="게시글 작성") #컨트롤러에 요론 식으로 적어준다
public ResponseEntity<Board> createBoard(@RequestBody BoardDTO board) {
    Board createdBoard = boardService.postBoard(board);
    return new ResponseEntity<>(createdBoard, HttpStatus.CREATED);
}

@Entity
@Table(name = "board")
@Getter @Setter
@AllArgsConstructor @NoArgsConstructor
public class Board {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @ApiModelProperty(value = "board_id ")
    private Long boardId;

    @Column(nullable = true, name = "user_id")
    @ApiModelProperty(value = "user_id")
    private String userId;

}

 

4. java.lang.NullPointerException 발생

해당 에러가 발생했다면

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

application.properties에 이 줄을 추가해주면 된다.

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

 

5. 404에러가 발생했다

의존성 추가

bundle.gradle에서

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

or

pom.xml

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

 

6. java.lang.NoSuchMethodError: 'boolean io.swagger.v3.oas.models.media.Schema.getExampleSetFlag()'

그만 괴롭혀!!!

여기저기 찾아본 결과 결국 버전이 안맞아서 생겼던 문제였다..

springfox-swagger-ui 3.0.0과 openapi의 버전 호환성 문제였던 것 같다.

implementation group: 'io.springfox', name: 'springfox-swagger2', version: '3.0.0'
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

 

00. 문서 실행

3.x :
http://localhost:{포트번호}/swagger-ui/index.html
http://localhost:{포트번호}/swagger-ui/

2.x : http://localhost:{포트번호}/swagger-ui.html

 

결과

 

 

+ 명세서의 info가 바뀌지 않는 문제

Swagger 3버전에서는 SwaggerConfig 대신 OpenApiConfig로 대체해줘야 하는 것 같다.

참고자료

https://wildeveloperetrain.tistory.com/156 

Spring swagger 3 사용방법(springdoc-openapi-ui)