[Spring] Swagger 📌

https://github.com/xx10222/selab-todo-list/wiki/Swagger

GitHub - xx10222/selab-todo-list: SELAB TODO-LIST STUDY

투두리스트를 하면서 위키에만 정리해뒀던 Swagger,,

내일 스터디 발표를 위해 그냥 각잡고 정리를 하려고 한다!

---

🖐 문서화의 필요성

• 일반적으로 웹 서비스를 구현하면 간단한 구조더라도 위와 같은 형태를 유지한다
• 이런 구조로 개발하거나 유지보수를 진행할 경우, 해당 API 서버가 어떤 Spec을 가진 데이터를 주고 받는지에 대한 문서 작업이 필요하다
• 하지만 이런 문서 작업은 번거롭고, 변경할 때마다 작업하기가 쉽지 않다
• 따라서 API Spec 문서를 자동화 하는 것이 등장하였다

 

---

 

Swagger

• API의 문서를 자동으로 정리해주는 오픈소스 프레임워크이다
• 해당 Swagger를 협업하는 개발자에게 전달하면 Path, Request, Response, 제약 조건 등을 한번에 알 수 있다
• API 문서 자동화 뿐만 아니라 Swagger를 통해 파라미터를 넣어보고 테스트할 수 있다
• Swagger를 사용하면 API 문서를 작성하는 시간 절약이 가능하고, API 정보를 실시간으로 유지할 수 있다
• Swagger가 적용될 경우 설정된 URL 리스트들의 목록을 바로 확인할 수 있다
• 단순히 보여주기만 하는 것이 아닌 api에 대한 테스트도 진행할 수 있다

 

💡 Springfox vs Springdoc
- Swagger를 Spring에서 쉽게 사용할 수 있도록 도와주는 라이브러리
- 원래 Springfox를 주로 사용하다가 중간에 개발이 멈춰 SpringDoc의 사용 추세가 늘었다
- 하지만 현재 Springfox 개발이 다시 시작되어 많이 사용되기 시작했다
- 두 라이브러리에 문서화 및 테스트 등 기능에 큰 차이가 없고, 로직에도 영향을 주지 않기 때문에 상관 없지만 주로 Springfox가 더 많이 사용된다

 

 

 

Swagger 설정하기

Spring Boot와 Gradle을 기반으로 설정해보자

 

1) 의존성 추가

// swagger
compile 'io.springfox:springfox-swagger2:2.9.2'
compile 'io.springfox:springfox-swagger-ui:2.9.2'

build.gradle 에 의존성을 추가한다 (2.9.2 버전 기준)

 

 

2) 프로젝트에 Swagger 설정을 Bean으로 등록

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket apiV1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("groupName1")
                .select()
                .apis(RequestHandlerSelectors.
                        basePackage("com.app.edit"))
                .paths(PathSelectors.ant("/v1/api/**"))
                .build()
                .apiInfo(apiInfo());
    }

    @Bean
    public Docket apiV2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .groupName("groupName2")
                .select()
                .apis(RequestHandlerSelectors.
                        basePackage("com.app.edit"))
                .paths(PathSelectors.ant("/v2/api/**"))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "Title",
                "Description",
                "version 1.0",
                "https://naver.com",
                new Contact("Contact Me", "https://daum.net", "colt@colt.com"),
                "Edit Licenses",
                "https://naver.com",
                new ArrayList<>()
        );
    }
}

• 설정 클래스를 정의한 후, @EnableSwagger2 어노테이션을 선언해주고, @Bean 어노테이션을 통해 Docket 객체를 빈으로  등록해준다

 

 

@EnableSwagger2

• Swagger2 버전을 활성화하겠다는 어노테이션

 

Docket

• Swagger 설정을 할 수 있게 도와주는 클래스
• API 자체에 대한 정보는 컨트롤러에서 작성한다

 

useDefaultResponseMessages()

• Swagger에서 제공해주는 기본 응답 코드 (200, 401, 403, 404)
• false로 설정하면 기본 응답코드에 대한 메시지를 제거해준다

 

groupName()

• Docket Bean이 한 개일 경우 생략해도 상관없으나, 둘 이상일 경우 충돌을 방지해야 하므로 설정해줘야 한다

 

select()

• ApiSelectorBuilder를 생성하여 apis()와 paths()를 사용할 수 있게 해준다

 

apis()

• api 스펙이 작성되어 있는 패키지를 지정한다
• 즉, 컨트롤러가 존재하는 패키지를 basepackage로 지정하여 해당 패키지에 존재하는 API를 문서화한다

 

paths()

• apis()로 선택된 API 중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화한다
• PathSelectors.any() 로 설정하면 패키지 안에 모든 API를 한번에 볼 수 있다

 

apiInfo()

• 제목, 설명 등 문서에 대한 정보들을 설정하기 위해 호출한다

• apiInfo()의 파라미터 정보는 위와 같다

 

 

ParameterBuilder + globalOperationParameters()

• parameterBuilder와 globalOperationParameters()를 이용해서 위와 같이 Swagger의 전체 API에서 보여줄 파라미터를 설정해줄 수도 있다

 

 

globalResponseMessage()

• 위와 같이 globalResponseMessage()로 모든 operation에 공통된 응답 메시지를 작성할수도 있다

 

---

Swagger 설정이 완료되었다면, 서버를 실행한 후 http://localhost:8080/swagger-ui.html 로 접속하면 API가 문서화된 화면을 볼 수 있다

 

💡 참고

swagger-ui.html로 접속하는 이유는 springfox-swagger-ui 가 해당 파일을 만들어주기 때문이다

 

 

 

Controller에서의 Swagger 설정

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "hello", tags = {"swagger", "v1", "api"})
@RequestMapping("/v1/api")
@RestController
public class SwaggerController {

    @ApiOperation(value = "this is test!", notes = "note!!!!!")
    @PostMapping("/test")
    public String test(@ApiParam(name = "first param", value = "first value", required = true) String input,
                       @ApiParam(name = "second param", value = "second value", required = false) String input2) {
        return "test";
    }
}

 

 

@Api

• 해당 클래스가 Swagger 리소스라는 것을 명시한다
• value : 사용자 지정 이름을 붙일 수 있다. tags 사용시 무시된다
• tags : 사용하여 여러 개의 태그를 정의할 수도 있다

 

 

@ApiOperation

• 한 개의 Operation을 선언한다
• value : API에 대한 요약을 작성한다. 제대로 표시되려면 120자 이하여야 한다.
• notes : API에 대한 자세한 설명을 작성한다.

 

 

@ApiParam

• 파라미터에 대한 정보를 명시한다
• name : 파라미터 이름을 작성한다
• value : 파라미터 설명을 작성한다
• required : 필수 파라미터이면 true, 아니면 false를 작성한다

 

 

 

Swagger 주의사항

• API 문서 URL을 알고 있다면 아무나 들어와서 테스트를 할 수도 있다
• 따라서 사전에 접근 권한의 제한 등을 권한이 있는 사용자만 접근할 수 있도록 Spring Security 등의 설정을 해주어야 한다

 

 

 

 

---

참고)

https://chanos.tistory.com/entry/Spring-API-%EB%AC%B8%EC%84%9C-%EC%9E%90%EB%8F%99%ED%99%94%EB%A5%BC-%EC%9C%84%ED%95%9C-Swagger-300-%EC%A0%81%EC%9A%A9

[Spring] API 문서 자동화를 위한 Swagger 3.0.0 적용

https://velog.io/@banjjoknim/Swagger

Swagger로 API 문서 자동화를 해보자