HomeAboutMeBlogGuest
© 2025 Sejin Cha. All rights reserved.
Built with Next.js, deployed on Vercel
🍗
[New] 조규현팀/
🏗️
Tech Store/
📝
Swagger VS RestDocs
📝

Swagger VS RestDocs

담당자들
카테고리
Skill
주제
API 문서화
나의 블로그
완료율%
프로젝트
인스타뀨램
상태
완료
💨What [restDocs와 Swagger란 무엇인감]RestDocsSwaggerSpring 진영의 문서화 프레임워크✅How [어떻게 사용해야 하는감]Swagger 3.0 issue❓Why [왜 사용해야 하는감]📌 REFERRestDocsSwagger

💨What [restDocs와 Swagger란 무엇인감]

  • RestDocs와 Swagger는 자동으로 API 문서를 작상할 수 있게 해주는 라이브러리 이다.
  • “API 문서” 를 제공하는 방식의 양대 산맥이다.
 

RestDocs

  • 테스트 코드 기반으로 자동으로 API 문서를 작성해줌.
  • TEXT로 명세된 API 설명
동작원리
notion image
  • Test Case를 수행하면 산출물이 .adoc 파일로 /build/generate-snippets 디렉토리에 생성됩니다. (default path)
  • /src/docs/asciidoc 디렉토리에 /build/generate-snippets에 있는 adoc 파일을 include하여 문서를 생성할 수 있습니다.
    • /build/generate-snippets/*.adoc 파일들은 API Request, Response에 대한 명세들만 있는 파일이고
    • /src/docs/asciidoc/*.adoc 파일들이 실제 사용자에게 html파일로 변환되어 제공되는 API 문서 파일입니다.
    • 따라서 /src/docs/asciidoc/*.adoc 에 API 문서를 작성하고,필요한 API Request, Response Spec은 자동 생성된 /build/generate-snippets/*.adoc 파일들을 이용해 표현해줍니다.
    • 이렇게 하면 향후 API Spec이 변경되더라도, 문서를 수정하지 않아도 되는 장점이 있습니다.
  • 이렇게 생성된 asciidoc 문서는 AsciidoctorTask를 통해 html 문서로 processing 되어 /build/asciidoc/html5 하위에 html문서로 생성됩니다.
    • html 문서가 생성되는 기준은 /src/docs/asciidoc/*.adoc 파일을 기준으로 생성됩니다
 
 

Swagger

  • 어노테이션을 이용하여 API 문서를 작성해줌.
  • TEXT + 호출할 수 있는 UI 제공
 

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

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

✅How [어떻게 사용해야 하는감]

 
  • swagger 직접 보여주기
      • [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 issue

  • 주의 사항 2.0과 다르게 url 접속 엔드포인트가 달라짐
      • 🙅🏻. http://localhost:8080/swagger-ui.html
      🆗  http://localhost:8080/swagger-ui/로 바뀌었다
java-swagger-ui-3.0-사용하기
그동안 이직하고 적응하느라 바빴다는 핑계로.. 글을 쓰지 않다가 정말 오랜만에 글을 하나 쓴다. 별로 대단히 길게 쓸 글은 아니고, 최근 개인 프로젝트를 시작하며 그동안 손에서 놓아두었던 java 개발을 다시 하려고 프로젝트 셋팅을 진행하다가 삽질한 경험이다. swagger가 어느덧 3.0 버전이 나왔다길래 사용해볼까 싶어서 셋팅 하다 보니 뭔가 생각대로
https://blog2.deliwind.com/20201127/java-swagger-ui-3-0-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0/
java-swagger-ui-3.0-사용하기
  • 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 사용법
 

❓Why [왜 사용해야 하는감]

🧑🏻‍💻
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