OpenAPI ์ Swagger-ui ์ ์ฉํ๊ธฐ
ใ๏ปฟAPI๋ฅผ ๊ฐ๋ฐํ๊ณ ์ฌ์ฉ๋ฐฉ๋ฒ์ ๋ํ ๋ช ์ธ๋ฅผ ์์ฑํ๋ ๋ฐฉ๋ฒ์ ์ฌ๋ฌ ๊ฐ์ง๊ฐ ์๋ค. ๊ฐ์ฅ ์ฌํํ๊ฒ ๊ฐ๋ฐ ์ฝ๋์๋ ๋ณ๋๋ก ์ง์ ์๊ธฐ๋ก ์์ฑํ์ฌ ํ์ผ ํน์ ๋ฌธ์ ๋งํฌ๋ฅผ ์ ๋ฌํ๋ ๋ฐฉ๋ฒ์ด ์๋ค. ํ์ง๋ง ๊ฐ๋ฐ ์ฝ๋์ ๋ณ๋๋ก ์ง์ ์์ฑ์ ํ๋ค๋ ์ ์์ ์คํ/์ค์๊ฐ ๋ฐ์ํ ์ ์๊ณ ์ต์ ํ๊ฐ ์๋๋ ์ฌ๋ฌ ๊ฐ์ง ๋ฌธ์ ๊ฐ ๋ฐ์ํ๋ค. ๊ทธ์ ๋ฑ์ฅํ API ๋ฌธ์ํ ์๋ํ ํด์ ์๋ ์ฐ๋งฅ์ธ SpringRestDocs ์ Swagger.
ใ๏ปฟ๊ณผ๊ฑฐ SpringRestDocs ์ ๋ํ ํฌ์คํ ์ ํ๊ธฐ์ ์ด๋ฒ์ Swagger์ ๋ํ ์ฌ์ฉ๋ฐฉ๋ฒ์ ๋ํด ์ ๋ฆฌํด๋ณด๊ณ ์ ํ๋ค. ์ด ๋์ ์ฅ๋จ์ ์ ๋๋ฌด ๋๋ ทํ๊ธฐ์ API๋ฌธ์๋ฅผ ์ ๊ณตํ๋ ์ํฉ์ ๋ฐ๋ผ ์ ์ ํ๊ฒ ์ ํํ์ฌ ์ฌ์ฉํ ์ ์์์ผ๋ฉด ์ข๊ฒ ๋ค.
๏ปฟSpringBoot์ Swagger ์ ์ฉ
ใ๊ธฐ๋ณธ SpringBoot ๊ฐ ์ ํ ๋์ด ์๋ค๋ ๊ฐ์ ํ์ Swagger ๊ด๋ จ dependency๋ฅผ ์ถ๊ฐํด์ฃผ์. ์์ฐธ, ์ด์ ๋ถํฐ์ ํ๋ก์ ํธ ์ ํ ์ Gradle๋ก ํ๋ คํ๋ค. (๋ฌผ๋ก Maven์ผ๋ก ํด๋ ๋ฌด๋ฐฉํ์ง๋ง…)
dependencies {
implementation "io.springfox:springfox-boot-starter:3.0.0"
}
ใ๏ปฟ์ดํ JavaConfig ์ ์๋์ ๊ฐ์ด ์ค์ ํ๋๋ฐ ์๋ ๋ด์ฉ์ ์์ฃผ ๊ธฐ๋ณธ ์ธํ ์ด๋ ์์ธํ ๋ด์ฉ์ ๊ณต์ ๋ํ๋ฌธ์๋ฅผ ์ฐธ๊ณ ํด ๋ณด๋ฉด ์ข์ ๊ฒ ๊ฐ๋ค. (๋ฌผ๋ก ์ํ ํ๋ก์ ํธ๋ฅผ ๋ง๋ค๋ฉฐ ํ์ํ ๊ฒ ๊ฐ์ ๋ด์ฉ์ ์๋์์ ์ค๋ช ํ๊ฒ ๋ค.)๏ปฟ
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
ใ๏ปฟํ
์คํธํ ์ปจํธ๋กค๋ฌ๋ฅผ ์๋์ฒ๋ผ ์ฌํํ๊ฒ ์์ฑํ๊ณ (์ฌ์น์ฐ์ฐ…) ์คํ์ ์ํจ ํ /swagger-ui/
์ ์ ์์ ํด๋ณด๋ฉด swagger ๊ด๋ จ javaConfig ํ๋๋ง ์ถ๊ฐํ๋๋ฐ ๋ฌธ์๊ฐ ๋ง๋ค์ด์ง ๊ฒ์ ํ์ธํ ์ ์๋ค. (http method๋ ํธ์์ ๋ค์ํ๊ฒ ์์ฑํ์ผ๋ ์ DELETE ์ธ๊ฐ๋ผ๋ ์๋ฌธ์ ์ ์ด๋์.)
@RestController
public class SampleController {
@GetMapping(value = "/addition")
public Integer addition(Integer num1, Integer num2) {
return num1 + num2;
}
@PostMapping(value = "/subtraction")
public Integer subtraction(Integer num1, Integer num2) {
return num1 - num2;
}
@PutMapping(value = "/multiplication")
public Integer multiplication(Integer num1, Integer num2) {
return num1 * num2;
}
@DeleteMapping(value = "/division")
public Integer division(Integer num1, Integer num2) {
return num1 / num2;
}
}

ใ๏ปฟ์์์ ํ๋ ์ค์ ๋ค ์ค ๋ช ๊ฐ์ง๋ง ์ข ๋ ์์ธํ ์ดํด๋ณด์.
์ค์ | ์ค๋ช |
---|---|
Docket | ๏ปฟSpringfox ํ๋ ์ ์ํฌ์ ๊ธฐ๋ณธ ์ธํฐํ์ด์ค๊ฐ ๋ ๋น๋๋ก ๊ตฌ์ฑ์ ์ํ ์ฌ๋ฌ ๊ฐ์ง ๊ธฐ๋ณธ๊ฐ๊ณผ ํธ๋ฆฌํ ๋ฐฉ๋ฒ์ ์ ๊ณตํ๊ณ ์๋ค. ์ดํ select() ๋ก ApiSelectorBuilder๋ฅผ ๋ฐํ๋ฐ์ ์ฌ์ฉํ ์ ์๋๋ก ํด์ค๋ค. |
apis | ๏ปฟ์ด๋ค ์์น์ ์๋ API๋ค์ ๊ฐ์ ธ์ฌ ๊ฒ์ธ๊ฐ์ ๋ํ ์ ์. RequestHandlerSelectors.any() ์ด๋ผ๊ณ ํ์ผ๋ SpringBoot์์ ๊ธฐ๋ณธ์ผ๋ก ์ ๊ณตํ๋ basic-error-controller ๋ API ๋ฌธ์๋ก ๋ง๋ค์ด์ง ๊ฒ์ ํ์ธํ ์ ์๋ค. ํน์ ํจํค์ง๋ง ์ ์ฉํ๊ธฐ ์ํด์๋ RequestHandlerSelectors.basePackage("com.taetaetae.swagger.api") ์ ๊ฐ์ ํ์์ผ๋ก ์ง์ ํ๋ฉด ํด๋น ํจํค์ง ํ์์ ์๋ Controller๋ฅผ ๊ธฐ์ค์ผ๋ก ๋ฌธ์๋ฅผ ๋ง๋ค์ด ์ค๋ค๏ปฟ. |
paths | ๏ปฟ์ด๋ฆ์์๋ ๋์น๋ฅผ ์ฑ ์ ์๋ฏ์ด ํน์ path๋ง ํํฐ๋งํด์ ๋ฌธ์๋ฅผ ๋ง๋ค์ด ์ค๋ค. |
useDefaultResponseMessages | ๏ปฟ๊ธฐ๋ณธ http ์๋ต ์ฝ๋๋ฅผ ์ฌ์ฉํด์ผ ํ๋์ง๋ฅผ ๋ํ๋ด๋ ํ๋๊ทธ |
๏ปฟ์ด์ธ์๋ security ๋ ๊ณตํต์ผ๋ก ์ฌ์ฉ๋๋ ํ๋ผ๋ฏธํฐ ๋ฑ ๋ค์ํ ์ต์ ์ ์ค์ ํ ์ ์์ผ๋ ๊ฐ๋ฅํ๋ฉด ์ํฉ์ ๋ง๊ฒ ์ค์ ์ ๋ณ๊ฒฝํด ๋ณด๋ ๊ฒ๋ ์ข์ ๊ฒ ๊ฐ๋ค. ๋ค๋ฅธ ์ค์ ๋ค์ ์ถ๊ฐ์์ผ์ ์ข ๋ ์น์ ํ๊ฒ ๋ง๋ค์ด ๋ณด๋ฉด ์๋์ฒ๋ผ ๋ง๋ค ์ ์๊ณ ํด๋น ์ฝ๋๋ Github์์ ํ์ธ ๊ฐ๋ฅํ๋ค.

OpenAPI
ใ๏ปฟSwagger ๊ณต์ ํํ์ด์ง๋ฅผ ์ด๋ฆฌ์ ๋ฆฌ ๋๋ฌ๋ณด๋ฉด OpenAPI๋ผ๋ ๋ด์ฉ์ด ๋ง์ด ๋์จ๋ค. ๊ทธ๋ ๋ค๋ฉด OpenAPI๋ ๋ฌด์์ผ๊น? ๋ฌธ์์ ๋์์๋ ๋ด์ฉ์ ์ง์ญํด๋ณด๋ฉด Swagger ์ฌ์์ผ๋ก ์๋ ค์ ธ ์์ผ๋ฉฐ RESTful ์น ์๋น์ค๋ฅผ ์ค๋ช , ์์ฑ, ์๋น ๋ฐ ์๊ฐํํ๊ธฐ ์ํ ๊ธฐ๊ณ ํ๋ ๊ฐ๋ฅ ์ธํฐํ์ด์ค ํ์ผ์ ๋ํ ์ฌ์์ด๋ผ๊ณ ํ๋ค. ์ฆ, API ์์ฒด๋ฅผ ์ค๋ช ํ๋ ์ธํฐํ์ด์ค ์คํ์ด๋ผ๊ณ ์ดํด๋ฅผ ํด๋ณผ ์ ์๋ค. ์์์ ๋ง๋ค์ด์ก๋ Swagger๋ฅผ ๋ณด๋ฉด http://localhost:8080/v2/api-docs?group=Test API ๋ผ๊ณ ๋์์๋๋ฐ ์ด๋ฅผ ํด๋ฆญํด๋ณด๋ฉด ์๋์ ๊ฐ์ด json ํํ๋ก ๋ณด์ธ๋ค. ๋ค์ ๋ณด๋ฉด ์ฐ๋ฆฌ๊ฐ ์ด์ ๊น์ง Swagger์ผ๋ก ๋ง๋ API ๋ฌธ์๋ฅผ ์ค๋ช ํ๋ ์ธํฐํ์ด์ค ์คํ์ผ๋ก ์ดํดํ ์ ์๋ค. (๊ฝค ๊ธธ์ด์ ๋ง์ API๋ฅผ ์ ์ธํ๊ณ ์ง์ ๋ค.) ๊ทธ๋ ๋ค๋ฉด ์ด JSON ํ์ผ์ ์ด๋ป๊ฒ ํ์ฉํ ์ ์์๊น?๏ปฟ