[Spring Boot/RESTful] Swagger 설정(+버전 오류)

Swagger

API 설계, 빌드, 문서화, 사용에 도움을 주는 오픈소스 프레임워크

 

Swagger 구현

1. dependency 설정

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-boot-starter</artifactId>
      <version>3.0.0</version>
</dependency>

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>3.0.0</version>
</dependency>

버전 오류

spring boot 2.6 버전 이후에 spring.mvc.pathmatch.matching-strategy 값이 ant_path_matcher에서 path_pattern_parser로 변경되면서 몇몇 라이브러리(swagger포함)에 오류가 발생한다.

Failed to start bean 'documentationPluginsBootstrapper'; 
nested exception is java.lang.NullPointerException: 
Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" 
because "this.condition" is null

아래 값을 application.yml에 추가해줘야 함.

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

⇒ 하지만 얘는 뒤에서 다룰 actuator를 지원하지 않는다(actuator는 pathpattern-based parsing을 사용하기 때문)

 

2. Config 파일 설정

localhost:8088/v2/api-docs

localhost:8088/swagger-ui/index.html/ 두 링크에서 확인할 수 있다. 보통은 아래 걸 많이 쓴다.

@Configuration // 설정 관련 annotation
@EnableSwagger2 // SWAGGER 관련
public class SwaggerConfig {
	// localhost:8088/v2/api-docs
	// localhost:8088/swagger-ui/index.html/

	// Swagger Documentation
	private static final Contact DEFAULT_CONTACT = new Contact("Minji Kang",
		"https://github.com/test1234", "test1234@gmail.com");

	private static final ApiInfo DEFAULT_API_INFO = new ApiInfo("API TITLE",
		"My User Management REST API Service", "1.0", "urn:tos", DEFAULT_CONTACT,
		"Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<>());

	// asList : 배열 형태 -> 리스트 형태
	private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES = new HashSet<>(
		Arrays.asList("application/json", "application/xml")); // json과 xml 파일 형식을 지원함

	@Bean
	public Docket api(){
		return new Docket(DocumentationType.SWAGGER_2)
			.apiInfo(DEFAULT_API_INFO)
			.produces(DEFAULT_PRODUCES_AND_CONSUMES)
			.consumes(DEFAULT_PRODUCES_AND_CONSUMES);
	}

3. domain 설정

swagger에 나타낼 설명을 @ApiModel, @ApiModelProperty를 이용해 작성한다.

@Data
@AllArgsConstructor
@NoArgsConstructor // 디폴트 생성자 생성
@ApiModel(description = "사용자 상세 정보를 위한 도메인 객체")
public class User {
	private Integer id;

	@Size(min=2, message = "Name은 2글자 이상 입력해주세요.")
	@ApiModelProperty(notes = "사용자 이름을 입력해주세요.")
	private String name;

	@Past // 과거 날짜만 가능한 제약 조건
	@ApiModelProperty(notes = "사용자의 등록일을 입력해주세요.")
	private Date joinDate;

	@ApiModelProperty(notes = "사용자의 패스워드를 입력해주세요.")
	private String password;

	@ApiModelProperty(notes = "사용자의 주민번호를 입력해주세요.")
	private String ssn; // 주민등록번호
}

 

나중에 도움이 될 것 같은 질문

https://www.inflearn.com/questions/224450

Swagger와 Jackson Filter 사용 시 Swagger-ui의 example value - 인프런 | 질문 & 답변