Springboot 프로젝트에 swagger 적용하기

 

• Swagger란?
• Swagger를 써야하는 이유
• Springdox vs Springfox

 

 

Swagger란?

• 프로젝트의 API 문서를 쉽게 쓸 수 있도록 해주는 라이브러리
• 서버로 요청되는 API 리스트 등을 HTML 화면으로 문서화해줌 + 테스트도 가능
• Spring boot 기준: 서버가 가동되면서 @RestController를 읽어 API를 분석하여 HTML 문서를 작성함

 

Swagger를 써야하는 이유

• Rest API의 스펙을 문서화하는 것은 매우 중요하다
• API를 변경할 때마다 Reference 문서를 변경해야하는 것은 번거로움
• 협업 시 효율적이다

 

Springdoc Swagger  vs  Springfox Swagger

• Springdoc Swagger와 Springfox Swagger는 Spring Framework를 사용하는 프로젝트에서 Swagger를 이용할 수 있게 도와주는 라이브러리
• springfox swagger를 사용하다가 지원되지 않는 부분(그룹핑, 정렬)에 한계를 느껴 springdoc으로 넘어가는 사람이 있다고 함

 

Springfox Swagger

 

• 2015년에 처음 나와 2020년 3.0.0 버전을 마지막으로 업데이트가 중단됨
• Spring boot 2.6 이상 버전에서는 바로 적용이 안 된다고 한다
• 쓰이지 않는 분위기
• https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

 

Springdoc Swagger

 

• 2023-01-21 기준 1.6.14 가 최신버전.
• 마지막 업데이트는 2022년 12월 16일. 최근에도 업데이트 됨
• https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui

 

 

차이점

• Springdoc은 webflux라는 논 블록킹 비동기 방식의 웹 개발을 지원하도록 개발됨
• Springdox은 Springfox를 더 발전시킨 모습이며, 더 사용이 쉽다고 함.
• 그 외에도 Springdoc은 Springdoc에서는 그룹 간, api간 정렬이 가능하다고 하고, 중복되는 코드 양이 적어진다고 한다.

 

 Swagger 사용법

 

 

 

Try it out을 클릭 후 

json을 작성하고

execute를 누르면 테스트 완료

 

 

springboot로 swagger 사용 간단한 예제

 

간단하게 프로젝트를 만들어주었다

 

 

controller 하나를 만들어줌

 

 

HelloController.java

 

import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @GetMapping("hello")
    public String hello(Model model) {
        model.addAttribute("data", "hello!!");
        return "hello";
    }
}

 

 

pom.xml에 두 줄 추가

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.0</version>
</dependency>

(gradle은 이거 입력)

// https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui
implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.0.2'

// https://mvnrepository.com/artifact/javax.xml.bind/jaxb-api
implementation group: 'javax.xml.bind', name: 'jaxb-api', version: '2.3.0'

 

 

 

 

http://localhost:8080/swagger-ui/index.html 에 접속

 

 

아주 잘 나오는 걸 확인할 수 있다 ㅎㅎ

 

 

 

 

 

포맷대로 만들어지니까 테스트가 아주 편해진다.

원래는 postman을 사용했었는데 이제 swagger를 애용할 것 같다

 

 

 

 

 

 

 

 

 

 

 

참고:

https://springdoc.org/v2/

https://velog.io/@jeong-god/Spring-boot-Swagger-API-%EC%97%B0%EB%8F%99%ED%95%98%EA%B8%B0

https://velog.io/@ychxexn/Swagger-%EB%8B%A4-%EA%B0%99%EC%9D%80-%EB%86%88%EC%9D%B4-%EC%95%84%EB%8B%88%EC%97%88%EB%8B%A4.-Springfox-vs-Springdoc

https://www.youtube.com/watch?v=Q27PGBYmHNA&list=PLlTylS8uB2fBOi6uzvMpojFrNe7sRmlzU&index=11