[Java/Spring] Swagger (1) springfox 이용

Swagger란?

개발한 REST API를 편리하게 문서화 해주고 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트

Spring boot에서는 간단하게 springfox-boot-starter를 gradle dependencis에 추가함으로 사용할 수 있다.

Swagger Annotation

Swagger 실행

1. dependencis 추가

1) 아래의 url에서 원하는 버전을 선택해 의존성을 추가 할 수 있다

https://mvnrepository.com/search?q=springfox

2) 3.0.0 버전 선택 시 (SpringFox Swagger2 + SpringFox Swagger UI)

• 기존엔 "SpringFox Swagger2 + SpringFox Swagger UI" 두 가지를 추가해서 사용해야 했으나 3.0.0 버전부터는 아래의 SpringFox Boot Starter를 통해 통합해서 이용 할 수 있다.
  

• Gradle 사용 : 아래의 코드를 복사해서 의존성 추가한다.

// https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter
implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'

• build.gradle 추가

plugins {
	id 'org.springframework.boot' version '2.7.4'
	id 'io.spring.dependency-management' version '1.0.14.RELEASE'
	id 'java'
}

group = 'com.example.swaggerapi'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

configurations {
	compileOnly {
		extendsFrom annotationProcessor
	}
}

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	compileOnly 'org.projectlombok:lombok'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	// https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter
	implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
}

tasks.named('test') {
	useJUnitPlatform()
}

2. Controller

아래와 같이 TestController를 만든 후 SwaggerUi가 연결 되었는지 확인한다.

package com.example.swaggerapi.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api")
public class ApiController {
	
	@GetMapping("/hello")
	public String hello() {
		return "hello ila world";
	}
}

3. 버전 오류 해결

실행 후 아래와 같이 오류가 난다면 버전 오류 일 수 있다.

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

출처: https://skmouse.tistory.com/entry/SpringBoot-Swagger-에러-Failed-to-start-bean-documentationPluginsBootstrapper-nested-exception-is-javalangNullPointerException [SK_MOUSE 개발일기:티스토리]

버전 해결을 위해 application.properties에 아래 문장을 추가한다.

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

4. Swagger UI 접속

http://localhost:9090/swagger-ui/

위 경로로 접속하면 컨트롤러로 자동 연결 된 것을 확인 할 수 있다.

Execute 해보면 실행 된 것도 확인 할 수 있다.