[Spring Boot] Swagger로 API 문서를 자동으로 만들기

👨‍💻 블로그 방문에 감사합니다!

안녕하세요. 팀드모네입니다.

오늘은 Swagger로 API 문서를 자동으로 만드는 방법을 공유드립니다.

포스팅을 따라하시면, Swagger를 바로 써먹을 수 있도록 안내해보겠습니다.

🎯 설명에 앞써서.. 사용하는 프로젝트 버전은?

- 개발 도구: IntelliJ Ultimate
- Spring Boot: 2.1.8.RELEASE
- Java 11
- Spring Web 의존성 추가 [build.gradle]

 

설명에 앞써 간단하게 용어 정리를 하겠습니다.

 

🎯 스웨거란?

-> API를 개발할 때 쓰는 툴을 의미합니다.

-> API를 구현하고 시각화하기 위해 개발된 오픈소스입니다.

-> API 설계 + 문서화 + 테스트 및 배포까지 전과정을 함께합니다.

referrence : https://swagger.io/

 

이제 실무 작업을 진행하겠습니다.

🎯 1. build.gradle에 의존성 추가

Springfox Swagger2 하위 버전은 취약점이 발견되었으니 꼭 최신버전을 사용합시다!

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

 

🎯 2. SwaggerConfiguration.java를 생성

import org.springframework.context.annotation.*;
import springfox.documentation.builders.*;
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 api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ointex.noticeboard"))
                .paths(PathSelectors.any())
                .build();
    }

    /*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<>()
        );
    }*/
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("제목 작성")
                .version("버전 작성")
                .description("설명 작성")
                .license("라이센스 작성")
                .licenseUrl("라이센스 URL 작성")
                .build();
    }
}

.apis()는 API 문서를 만들어줄 범위를 지정하는 것이다.

.paths()는 .paths(PathSelectors.ant("api/v1/**")) 와 같이 사용한다.

http://localhost/api/v1/ 하위 경로를 가지는 API에 대해 문서를 생성하는 것이다. 

 

🎯 3-1 혹시 이런 에러가 나면?

Cannot resolve symbol 'EnableSwagger2' issue in Spring boot (symbol: class EnableSwagger2)

File > Invalidate Caches..를 선택하여 intelliJ를 재시작합니다.

 

🎯 4. 결과 확인

이제 작업의 결과를 확인할 시간이다.
로컬에서 서버를 띄웠다는 가정 하에 접속하면 되는 URL은 다음과 같다.

http://localhost:8080/swagger-ui.html

 

 

혹시 위 URL이 동작하지 않은 경우, Gradle을 참고하면 해결의 실마리를 얻을 수 있습니다.

*Springfox는 버전에 따라 접속 URL이 바뀌니 주의해야한다.

 

👉 총 정리 

최근 관리 중인 API가 동작이 안하여 매우 당황한 경험이 있었습니다. API를 문서로 작성하였기 때문에 개선 이력이 유실되었고 그것에 대해서 인수인계가 잘 안 된 것이죠. 신규 프로젝트를 시작할 때도 API와 Mobile 연동 테스트를 할 때도 애로사항이 있었습니다. 하지만 이제 Swagger를 통해 그 문제들을 해소할수 있을 것 같은 기분이 듭니다.

 

• 2

블로그 방문해주셔서 감사합니다.

도움이 되셨으면 '좋아요'를 눌러주세요!
추가로 질문사항이 있으면 댓글 남겨주세요 :)

💯포스트 후원하기

▶유튜브 구독하기

---

reference : https://onedaycodeing.tistory.com/154

광고 링크 : https://ogx4.com

인공지능이 추천하는 10개의 게임!