[Spring Boot] Swagger 연동 및 설정(gradle)

Benjamin·2022년 10월 10일
2

Server

목록 보기
5/5

환경
Spring Boot 2.4.2
Java 11.0.6

Swagger?

OAS(Open Api Specification)를 위한 프레임워크이다.
개발자들의 필수 과제인 API문서화를 쉽게 할 수 있도록 도와주며, 파라미터를 넣어서 실제로 어떤 응답이 오는지 테스트도 할 수 있다.
또한, 협업하는 클라이언트 개발자들에게도 Swagger만 잘 전달해주면 API Path 와 request, response 값 및 제약 등을 한 번에 알려줄 수 있다.

서버로 요청되는 URL리스트를 HTML 화면으로 문서화 및 테스트 할 수 있는 라이브러리

왜 사용하는가?

협업을 진행하거나 이미 만들어져 있는 프로젝트에 대해 유지보수를 진행하게 되면 구축되어 있는 API서버가 어떤 스펙을 가지고 있는지 파악해야한다. 이러한 스펙 들을 직접 문서로 작성하게 되면 API가 변경될 때 마다 문서를 수정해야한다. 즉, 유지보수가 어려움.

이러한 어려움을 덜어주기 위해 만들어진 것이 Swagger이다.

swagger 설정하는 방법

설정하기 위한 라이브러리는 2가지가 있다.

  • Spring-Fox

    • 오래전에 나온 라이브러리(2015년)
    • 2020년 이후로 업데이트 멈춤
    • spring boot 2.6버전 이상에서는 바로 적용 안됨

  • Spring-Doc

    • 최근에 나온 라이브러리 (2019년)
    • 업데이트가 최근까지도 이루어짐
    • spring boot 2.6버전 이상 지원

주의할 점

초반에 아무 블로그를 들어가서 Swagger를 따라 추가했는데, 아무리해도 되지않는 현상을 겪었다.

그래서 사전에 반드시 체크하고 들어가야 하는 항목이 있다.

  1. 어떤 버전의 SpringBoot를 사용하는 지

  2. 어떤 버전의 Swagger를 추가할 것인지
    🍀 호환되지 않는 버전이있으니 꼭 조사 후 사용!

Swagger UI 환경설정

여기에서 사용할 버전을 참고하자
나는 많이 사용한듯한 2.9.2를 사용하였다.

swagger를 사용하기 위해서는 springfox-swagger2를 의존성에 추가해야 한다.
추가적으로 문서를 예쁘게 보여주고, 테스트 기능을 위해서 springfox-swagger-ui 의존성도 추가하겠다.

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

두 줄에 대해 build.gradle에서 dependencies를 추가한다.

SwaggerConfiguration.java

나는 src-main-java-com-example-demo-utils 아래에 생성하였다.

import java.util.HashSet;
import java.util.Set;

import javax.servlet.ServletContext;

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 {

  @Bean
  public Docket SwaggerApi(ServletContext servletContext) {

    return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(swaggerInfo())
                .groupName("Anding")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.src"))
                .paths(PathSelectors.ant("/app/**"))
                .build()
                .useDefaultResponseMessages(false);
  }

  private Set<String> getConsumeContentTypes() {
      Set<String> consumes = new HashSet<>();
      consumes.add("application/json;charset=UTF-8");
      consumes.add("application/x-www-form-urlencoded");
      return consumes;
  }

  private Set<String> getProduceContentTypes() {
      Set<String> produces = new HashSet<>();
      produces.add("application/json;charset=UTF-8");
      return produces;
  }

  private ApiInfo swaggerInfo() {
    return new ApiInfoBuilder().title("Anding API Documentation")
                .description("Anding팀의 API입니다")
                // .license("")
                // .licenseUrl("")
                .version("1.0")
                .build();
  }

}
  • apis의 basePackage는 리소스들(users,stores...)이 있는 상위폴더까지 지정해주면, 이하 폴더를 전부 인식한다.

Docket

Swagger 설정의 핵심이 되는 Bean
API 자체에 대한 스펙은 컨트롤러에서 작성한다.
[설정 정보]

  • useDefaultResponseMessages() : false로 설정하면, swagger에서 제공해주는 응답코드 ( 200,401,403,404 )에 대한 기본 메시지를 제거합니다.
    불필요한 응답코드와 메시지를 제거하기 위함이며, 필요 응답코드와 메시지관련하여서는 컨트롤러에서 명시해준다.
  • groupName()
    -Docket Bean이 한 개일 경우
    기본 값은 default이므로, 생략가능
    -여러 Docket Bean을 생성했을 경우
    groupName이 충돌하지 않아야 한다
  • select()
    ApiSelectorBuilder를 생성합니다.
  • apis()
    api 스펙이 작성되어 있는 패키지를 지정합니다.
    즉, 컨트롤러가 존재하는 패키지를 basepackage로 지정하여, RequestMapping( GetMapping, PostMapping ... )이 선언된 API를 문서화합니다.
  • paths()
    apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화합니다.
  • apiInfo()
    제목, 설명 등 문서에 대한 정보들을 보여주기 위해 호출합니다.
    파라미터 정보는 다음과 같습니다.
    public ApiInfo( title, description, version, termsOfServiceUrl, contact, license, licenseUrl, vendorExtensions )

+swaggerInfo는 Swagger UI를 켰을 때, 상단에 보일 정보

Controller 설정

@RestController
@RequestMapping("/app/users")
@Api(value = "/app/users", description = "resource가 users인 API입니다") // swagger annotation
public class UserController {
    final Logger logger = LoggerFactory.getLogger(this.getClass());

    @Autowired
    private final UserProvider userProvider;
    @Autowired
    private final UserService userService;
    @Autowired
    private final JwtService jwtService;




    public UserController(UserProvider userProvider, UserService userService, JwtService jwtService){
        this.userProvider = userProvider;
        this.userService = userService;
        this.jwtService = jwtService;
    }

    /**
     * 회원 조회 API
     * [GET] /users
     * 회원 번호 및 이메일 검색 조회 API
     * [GET] /users? Email=
     * @return BaseResponse<List<GetUserRes>>
     */
    //Query String
    @ApiOperation(value="회원조회 API", notes="검색하는 회원에 대한 정보를 제공합니다.", response = SampleResponseObject.class, responseContainer = "List") // swagger annotation
    @ResponseBody
    @GetMapping("") // (GET) 127.0.0.1:9000/app/users
    public BaseResponse<List<GetUserRes>> getUsers(@ApiParam(value = "검색할 회원의 EMAIL", example = "anding@naver.com") @RequestParam(required = false) String Email) // swagger annotation
    { }

관련된 내용의 샘플 및 설명은 아래와 같다.

@Controller
@RequestMapping(value = "컨트롤러가 매핑되는 URL PATH")
@Api(value = "컨트롤러가 매핑되는 URL PATH", description = "controller 에 대한 설명을 써준다") // swagger annotation
public class SampleAPIController {
  @ApiOperation(        // swagger annotation
          value = "개별 API 에 대한 소개",
          notes = "개별 API 에 대한 설명",
          response = SampleResponseObject.class, responseContainer = "List"
  )
  @RequestMapping(value = "/{pathVariable}", method = RequestMethod.GET)
  public ResponseEntity<Collection<SampleResponseObject>> sendGetAPI(
          @ApiParam(value = "pathVariable 에 대한 설명", required = true)
          @PathVariable String pathVariable,
          @ApiParam(value = "파라미터에 대한 설명")
          @RequestParam(value = "limits", required = false) Integer limits,
          @ApiParam(value = "파라미터에 대한 설명", example = "예시")
          @RequestParam(value = "rollbackOptions", required = false) String rollbackOptions,
          @ApiParam(value = "Body 에 대한 설명", required = true)
          @RequestBody SampleRequestObject sRequestObject)

@Api : 클래스를 Swagger 리소스 대상으로 표시
@ApiOperation : 요청 URL 에 매핑된 API 에 대한 설명
@ApiParam : 요청 Parameter에 대한 설명 및 필수여부, 예제값 설정
@ApiResponse : 응답에 대한 설명

위 파일을 추가한 후, http://localhost:9000/swagger-ui.html에 접속

저는 spring boot의 포트를 9000으로 설정하였기때문에, 앞 url은 본인이 사용하시는 것으로 변경해서 접속하시면 됩니다.

참고사이트
https://velog.io/@borab/Spring-boot-Swagger-설정-gradle
https://velog.io/@changyeonyoo/Swagger-프로젝트-적용과-어노테이션
https://victorydntmd.tistory.com/341

profile
Benjamin
이전 포스트

[Spring-Boot] ec2서버에서 springboot사용하기위한 세팅(vscode SSH이용)

0개의 댓글