[Spring] 스프링 문서화(Spring DOC) - Swagger UI

📍Swagger UI 라이브러리 추가 

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

 

📍application.yml에 설정 추가

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

 

위 두 설정을 하고 나면 Swagger UI를 사용할 수 있다. 

 

 

 ++) application.yml에 설정 추가해주지 않으면 다음 에러가 발생한다. 

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

 

---

 

📍프로젝트 구조

---

 

★ Swagger 설정파일 - Swagger.config

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;

@Configuration
public class SwaggerConfig {

    // Swagger Docket 빈을 생성하여 API 문서화 설정을 반환
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                
                // 문서화할 대상 컨트롤러 패키지를 지정
                .apis(
                        RequestHandlerSelectors.basePackage("com.example.demo.member")
                                .or(RequestHandlerSelectors.basePackage("com.example.demo.product"))
                )
                // 모든 경로를 문서화 대상으로 지정
                .paths(PathSelectors.any())
                .build()
                // API 정보를 설정
                .apiInfo(apiInfo("스프링 수업", "v1.0"));
    }

    // API에 대한 정보를 설정하여 반환
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfo(
                title,  // API의 제목
                "스프링 문서화 Swagger 실습",  // API의 설명
                version,  // API의 버전
                "http://www.a.com",  // API에 대한 추가 정보 링크
                // API에 대한 연락처 정보 (이름, 블로그 주소, 이메일)
                new Contact("블로그 주소", "https://xoxoxoxox.tistory.com", "songyeon0607@naver.com"),
                "Licenses",  // API 라이선스
                "http://b.com",  // 라이선스에 대한 링크
                new ArrayList<>()  // Vendor Extensions (벤더 확장)
        );
    }
}

 

ApiInfo apiInfo() {}; API의 대한 정보 설정

- title : API 이름

- version : API 버전

 

RequestHandlerSelectors.basePackage(String packageName)

Swagger를 적용할 클래스의 package명을 명시

 

PathSelectors.any()

해당 package 하위에 있는 모든 url에 swagger 적용

---

그 외 파일들(컨트롤러와 메소드의 대한 이름 편집 작업)

 

MemberController

package com.example.demo.member.controller;

import com.example.demo.member.model.LoginMemberReq;
import com.example.demo.member.model.SignupMemberReq;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.Valid;

@RestController
@Api(value = "회원 컨트롤러 v1", tags = "회원 API")
@RequestMapping("/member")
public class MemberController {
    @ApiOperation(value = "로그인")
    @RequestMapping(method = RequestMethod.POST, value = "/login")
    public ResponseEntity login(@Valid LoginMemberReq loginMemberReq) {

        return ResponseEntity.ok().body("login process");
    }
    @ApiOperation(value = "회원 가입")
    @RequestMapping(method = RequestMethod.POST, value = "/signup")
    public ResponseEntity signup(SignupMemberReq signupMemberReq) {
        return ResponseEntity.ok().body("signup process");
    }
}

 

ProductController

package com.example.demo.product.controller;

import com.example.demo.member.model.SignupMemberReq;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "상품 컨트롤러 v1", tags = "상품 API")
@RequestMapping("/product")
public class ProductController {
    @RequestMapping(method = RequestMethod.GET, value = "/list")
    @ApiOperation(value = "상품 목록")
    public ResponseEntity list() {
        return ResponseEntity.ok().body("product list");
    }
}

 

LoginMemberReq

package com.example.demo.member.model;

import io.swagger.annotations.ApiParam;
import lombok.*;

import javax.validation.constraints.*;

@Builder
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class LoginMemberReq {
    @ApiParam(value = "회원의 이메일을 입력", required = true, example = "test01@test.com")
    private String email;

    @ApiParam(value = "회원의 패스워드를 입력", required = true, example = "qwer1234")
    private String password;

}

 

---

📍실행결과

위처럼 프로젝트를 실행시키고 아래 url로 접속하면 swagger-ui가 뜨게 된다.

API 이름들을 설정해준 대로 잘 뜨는 것을 확인할 수 있다.