[인프런 : spring-boot] Swagger 사용

개발자 도움말 페이지를 추가하는 Swagger에 대해 알아보려고 한다.

설계, 빌드, 문서화, 사용에 관한 기능을 지원해주는 Swagger라는 오픈소스를 이용해서 개발자 관련 도움말 페이지를 만들어 볼 것이다.

 

[ Swagger 란? ]

처음에는 단순한 JSON표현을 목적으로 시작했다가 문서를 자동화하기 위해 프로젝트가 발전되었다고 한다.

아파치 2.0 오픈소스 라이센스를 사용하고 있고 수많은 온라인 서비스들이 본인들의 제품을 소개하기 위해서 사용하고 있다.

 

[ Swagger 사용하기 ]

1. 라이브러리 추가하기

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

빨간색 오류가 나면 File > Invalidate Caches 로 한번 싹 지워주고 다시 Maven build 를 해보면 된다.

 

2. config 패키지 생성 후 SwaggerConfig 클래스 생성

package com.example.restfulwebservice.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

//설정 관련 어노테이션
@Configuration
//Swagger 관련 어노테이션
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    //api 관련된 document , 반환값으로 Docket 형태
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2);
    }

}

서버 재기동 후 웹 브라우저에서 확인해본다.

 

① http://localhost:8088/v2/api-docs

확인해보면

이런식으로 JSON 타입으로 정보를 확인 할 수 있다.

 

② http://localhost:8088/swagger-ui/index.html 로 확인해보면

이렇게 html형태로 나오는 것을 볼 수 있다.

 

 

---

  Swagger UI 는 일반 사용자들이 커스텀해서 사용할 수 있도록 지원해주는 도구인데 조금 자세하게 뜯어보자.

간략하게 줄여서 보면 이러한 정보들을 확인 할 수 있는데, 

                                                         info를 보면 라이선스들에 대한 정보들을 볼 수 있다.

처럼 paths 에서 hello-world 밑에 있는 것들도 다 확인해 볼 수 있다.

제일 밑에 있는 definitions 를 통해 현재 Swagger에서 사용되고 있는 다양한 인스턴스들을 만들때 사용된 객체도 표시된 것을 볼 수 있다.