스프링 부트 어플리케이션 Swaager 사용해서 API 문서 구성하기

백엔드와 프론트엔드가 서로 소통하기 위해 꼭 필요한 API 문서 관리! 

Swagger로 시작해보자!!

 

설정

먼저 나는 Maven 을 사용했기 때문에 pom.xml에 swagger와 관련된 dependency를 추가한다

 

pom.xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

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

물론 3. x 버전도 있는데 2.9.2를 제일 많이 사용한다고 한다

 

그리고 나서 config 폴더에 swaggerConfiguration 클래스를 생성한다

package com.trips.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
  // Docket: Swagger 설정의 핵심이 되는 Bean
  // API 자체에 대한 스펙은 컨트롤러에서 작성
  @Bean
  public Docket api(){
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.trips")) //디렉토리 경로를 적어준다
              .paths(PathSelectors.any())
              .build();
  }
  private ApiInfo apiInfo(){
      return new ApiInfoBuilder()
              .title("API with Swagger")
              .description("acti on&off swagger api 문서 입니다")
              .version("1.0.0")
              .build();
  }
}

이렇게 하고 애플리케이션을 구동하면

이런 식으로 swagger ui 나온다 짝짝 👏👏👏👏👏

title로 설정한 API with Swagger가 제목처럼 나오고

description이 밑에 설명 처럼 나온다

 

❗ 주의

만약 본인이 Spring boot 버전이 2.6.x 버전 이상이라면 

....because the return value of "springfox.documentation.spi.service.contexts.Orderings.patternsCondition(springfox.documentation.RequestHandler)" is null

이런 오류가 나올 수 있다. 해석해보자면 RequestHandler의 value가 null 이라는 얘기인 거 같은데

구글링을 열심히 해보니 Spring boot 버전과 호환성이 안 맞아서 그렇다고 한다

그러니 2.4.0 버전으로 pom.xml을 수정해보기를 권한다

 

 

API 정보 설명 설정(@ApiOperation)

API에 대한 설명도 설정할 수 있다

@Api(tags="게시판 API")
public class YdsBoardController {
	
	
	 @Autowired 
	 private ydsBoardService service;
	 
	
	@GetMapping("list")
	@ApiOperation(value ="목록 조회", notes="게시물 목록을 조회할 수 있습니다")
    public void getBoardlist(Model model, 
			@RequestParam(name="address", required=false) String address, 
			Authentication authentication) {
		....
	}

이렇게 어노테이션을 달아주면

이런 식으로 각 API에 대해 설명을 추가 해줄 수 있다

 

 

 

API 파라미터 상세 설명 설정(@APIImplicitParams, @APIImplicitParam)

@GetMapping("id")
	@ApiOperation(value ="상세 조회", notes="게시물 정보를 상세 조회할 수 있습니다")
	@ApiImplicitParams({
		@ApiImplicitParam(name = "num", value="게시물 번호", example="100")
	})
	public void getBoard(int num, Model model, MultipartFile[] file) {
		TripsBoardDto board = service.getBoard(num, file);

		model.addAttribute("board", board);
		
	}

이렇게 @APIImplicitParams, @APIImplicitParam 어노테이션을 달아주면

이렇게 parameter에 대한 설명도 넣어주고 기본값도 설정할 수 있다.

추가로 Try it out 을 누르면 이렇게 API 데이터를 보여준다