Swagger를 이용한 API 문서화

❓Swagger란?

Swagger는 Open API를 명세하기 위한 Open Api Specification(OAS) 프레임워크이다. API들이 가진 스펙을 명세하고, 관리하여 문서화 해주는 기능을 가지고 있다.

Swagger를 이용해 다른 개발팀과 협업, 프로젝트의 유지보수 , 백엔드 API 명세서를 작성해 보다 편리하게 관리하는 것이 가능하다.

⚙️ Spring Boot Swagger 설정

Spring Boot 프로젝트에 의존성 추가를 한다.

implementation 'io.springfox:springfox-swagger2:2.9.2'    #Swagger 애노테이션 사용가능
implementation 'io.springfox:springfox-swagger-ui:2.9.2'  #Swagger UI 사용가능 

프로젝트의 Config 패키지에 Configuration 클래스를 생성한다.

package com.yourecipe.member.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 SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()                                       
                .apis(RequestHandlerSelectors.any())            // Swagger API 문서로 만들기 원하는 basePackage 경로
                .paths(PathSelectors.any())                     // apis() 중에 path에 맞는 API 필터링 
                .build();
    }

    // Swagger로 설정하는 API 정보
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("YouRecipe Member API")
                .description("YouRecipe Member API Reference for Developers")
                .termsOfServiceUrl("https://github.com/jymaeng95/YouRecipe-Member")
                .license("@Zayson License")
                .licenseUrl("http://you-recipe.com").version("1.0").build();
    }
}

❗Swagger 주요 애노테이션

• @Api(tags = "", value = "") : Swagger 리소스임을 명시
• @Api(tags = "Member", value = "회원 컨트롤러") public class MemberController {...}

• @ApiOperation(value = "") : 한개의 Operation을 명세
• @ApiOperation(value = "회원 가입") @PostMapping public ResponseEntity<String> signUpMember(@RequestBody Member member) {...}

• @ApiModel : 모델 객체 명세
• @ApiModel(description = "회원 정보를 위한 도메인 객체") public class Member {...}
• @ApiModelProperty : 모델 객체 속성 명세
• @ApiModelProperty(value = "회원 ID") private int memberId;

🔗 참고

https://doozi316.github.io/web/2020/10/16/WEB29/