HomeAboutMeBlogGuest
© 2025 Sejin Cha. All rights reserved.
Built with Next.js, deployed on Vercel
🛁
공부기록/
🍀
Spring/
📓
Swagger
📓

Swagger

Swagger란?RestDocsSwaggerSpring 진영의 문서화 프레임워크스웨거는 어떻게 사용하는가?왜 사용해야 하는가?📌 REFERRestDocsSwagger
 

Swagger란?

  • 자동으로 API 문서를 작성할 수 있게 해주는 라이브러리다.
  • 동일한 기능을 제공해주는 것으로 RestDocs가 있다.
 

RestDocs

  • 테스트코드 기반으로 자동으로 API 문서를 제공해준다.
    • 테스트코드 기반이기 때문에 코드가 변경되거나 그럴 경우 신뢰하고 사용이 가능하다
  • TEXT로 명세된 API 설명
  • 동작원리
      • notion image
 

Swagger

  • 애노테이션을 이용해서 API 문서를 작성해준다.
  • TEXT +호출할 수 있는 UI를 제공한다.
 

Spring 진영의 문서화 프레임워크

ㅤ
RestDocs
Swagger
장점
제품 코드에 영향이 없다.
API 테스트 화면을 제공한다.
ㅤ
테스트와 함께 쓰일 수 있다.
적용하기 용이하다.(애노테이션 기반)
단점
적용하기 어렵다
제품코드에 애노테이션을 추가해야 한다.
ㅤ
ㅤ
제품코드와 동기화가 안될 수 있다.
 

스웨거는 어떻게 사용하는가?

  • 직접 동작하는 부분 확인하기
[Swagger] Open API 3.0 Swagger v3 상세설정
※ 실습 프로젝트는 Github 에서 확인 할 수 있습니다. Api문서를 쉽게 알아보기 위해선 Schemas 에 대한 설명과 들어갈 값에 대한 정보가 필요하다. 또한 api method에 대한 설명도 있어야 api구성 목록을 원활하게 식별할 수 있다. 이번 포스팅에서는 Swagger v3 Annotation을 이용하여 API 문서의 설명을 구체적으로 작성하고, Java Bean Validation 을 이용하여 api 사용시 유효성 체크를 하도록 한다.
[Swagger] Open API 3.0 Swagger v3 상세설정
https://jeonyoungho.github.io/posts/Open-API-3.0-Swagger-v3-%EC%83%81%EC%84%B8%EC%84%A4%EC%A0%95/
[Swagger] Open API 3.0 Swagger v3 상세설정
  • Swagger 3.0 이슈
    • 주의 사항 2.0과 다르게 URL 앤드포인트가 달라졌다.
      • http://localhost:8080/swagger-ui.html
      • http://localhost:8080/wagger-ui/ 로변경
        • blog2.deliwind.com
        https://blog2.deliwind.com/20201127/java-swagger-ui-3-0-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0/
      • yml property add 3.0에서는 반드시 필수적이다 !
        • [Error] SpringBoot 2.6.X 에서 swagger 3.0 사용법
        SpringBoot 2.6에서 swagger 3.0 사용 환경 : 인텔리제이 jdk1.8 SpringBoot 2.6.1 gradle Swagger 3.0.0 SwaggerUI 3.0.0 swagger를 적용하는 방법은 구글 검색하면 다른 분들이 잘 써놔서 검색하면 잘 나올것이다 그런데 나는 SpringBoot 2.6.1 환경.. jackyee.tistory.com
        [Error] SpringBoot 2.6.X 에서 swagger 3.0 사용법
        https://minutemaid.tistory.com/m/122
        [Error] SpringBoot 2.6.X 에서 swagger 3.0 사용법

왜 사용해야 하는가?

  • API Spec이 변경되거나 추가/삭제 되는 부분에 대해 항상 테스트코드를 수정해야 하며 API 문서가 최신화 될 수 있도록 해줘야한다.
 

📌 REFER

RestDocs

Spring Rest Docs 적용 | 우아한형제들 기술블로그
안녕하세요? 우아한형제들에서 정산시스템을 개발하고 있는 이호진입니다. 지금부터 정산시스템 API 문서를 wiki 에서 Spring Rest Docs 로 전환한 이야기를 해보려고 합니다. 현재 정산시스템은 API 문서를 wiki 로 공유하고 있었습니다. 며칠 전 API 에 필드를 추가하고 API 문서를 확인해보니 변경된 코드와 달랐습니다. 있어야 할 필드가 없었고 없어야 할 필드가 있었으며 같은 값을 주는 필드가 각기 다른이름의 필드로 제공되었습니다.
Spring Rest Docs 적용 | 우아한형제들 기술블로그
https://techblog.woowahan.com/2597/
Spring Rest Docs 적용 | 우아한형제들 기술블로그
Spring REST Docs
The aim of Spring REST Docs is to help you produce accurate and readable documentation for your RESTful services. Writing high-quality documentation is difficult. One way to ease that difficulty is to use tools that are well-suited to the job. To this end, Spring REST Docs uses Asciidoctor by default.
Spring REST Docs
https://docs.spring.io/spring-restdocs/docs/current/reference/html5/
Creating API Documentation with Restdocs
This guide walks you through the process of generating documentation for the HTTP endpoints in a Spring application. You will build a simple Spring application with some HTTP endpoints that expose an API. You will test only the web layer by using JUnit and Spring's MockMvc.
Creating API Documentation with Restdocs
https://spring.io/guides/gs/testing-restdocs/
Spring Rest Docs를 이용한 API 문서 만들기 | Carrey`s 기술블로그
Spring Rest API 문서를 자동으로 생성하고자 할 때, 보통 Swagger로 많이 사용하지만이번에는 Spring Rest Docs를 사용하여 API 문서를 자동으로 작성 할 수 있도록 해봤습니다. 포스팅에 작성된 코드는 https://github.com/jaehun2841/spring-rest-docs-example 에서 참고하시길 바랍니다.
Spring Rest Docs를 이용한 API 문서 만들기 | Carrey`s 기술블로그
https://jaehun2841.github.io/2019/08/04/2019-08-04-spring-rest-docs/#x2F-src-x2F-docs-x2F-asciidoc-%EB%94%94%EB%A0%89%ED%86%A0%EB%A6%AC-%EB%82%B4%EC%97%90-html%EB%A1%9C-%EC%A0%9C%EA%B3%B5%EB%90%A0-%EB%AC%B8%EC%84%9C%EB%A5%BC-asciidoc%EC%9C%BC%EB%A1%9C-%EC%9E%91%EC%84%B1
Spring Rest Docs를 이용한 API 문서 만들기 | Carrey`s 기술블로그
velog.io
https://velog.io/@kyle/%EC%84%9C%EB%B2%84-API-%EB%AC%B8%EC%84%9C%ED%99%94Spring-Rest-docs
Spring REST Docs 적용 (Gradle 7)
이 글은 Pick-Git 기술 블로그 에 업로드한 글입니다. 안녕하세요, 케빈입니다. Pick-Git 서비스 개발 초기에는 프론트엔드 팀원들과 API 스펙 협의 후 Notion에 작성해서 공유했었는데요. 해당 방법에는 여러 문제점이 존재했습니다. 수기로 작성하다 보니 인적 실수로 인해 오기재 하는 경우가 많았습니다. 또한 개발 과정에서 API 스펙 변경이 매우 빈번하게 발생하는데, 이를 미기재하는 실수로 인해 일정에 차질이 종종 생기곤 했습니다.
Spring REST Docs 적용 (Gradle 7)
https://xlffm3.github.io/spring%20&%20spring%20boot/rest-docs/
Spring REST Docs 적용 (Gradle 7)

Swagger

https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
spring boot swagger 적용하기
spring boot 테스트 프로젝트로 swagger를 적용해보았다. 1. gradle에 해당 springfox-swagger를 명시해준다. swagger2, swagger-ui, swagger-annotations, swagger-models를 받아주는데 해당 정보는 mvn repository에서 확인할 수 있다. mvnrepository.com/artifact/io.springfox/springfox-swagger2/2.9.2 mvnrepository.com/artifact/io.springfox/springfox-swagger-ui/2.9.2 mvnrepository.com/artifact/io.swagger/swagger-annotations/1.5.21 mvnrepository.com/artifact/io.swagger/swagger-models/1.5.21 gradle 설정이 완료되면 ToySwaggerConfig 파일을 하나 생성해준다. 먼저 WebMvcConfigurer를 implements 받고 addResourceHandlers를 구현해준다. swagger-ui가 보여질 화면의 리소스 위치를 설정해주는 것이다.
spring boot swagger 적용하기
https://shlee0882.tistory.com/287
spring boot swagger 적용하기
Springfox Reference Documentation
https://springfox.github.io/springfox/docs/current/#swagger-1-2-vs-swagger-2-0