# Swagger

lnh03280

🚨 Swagger 란? > Swagger는 RESTful API를 문서화하고, 사용자가 쉽게 테스트하고 호출할 수 있도록 하는 도구이다. Swagger가 나오기 전 ➡️ FE 개발자와 BE 개발자간의 소통방식은 단순무식했습니다. BE가 문서로 일일히 URL 및 Request, Response를 적어서 FE에게 전달하는 방식을 사용 🏷️ BE 개발자가 API 문서를 일일히 작성해야 했기 때문에 생산성이 떨어졌습니다. 또한 문서의 일관성이 떨어지고, API가 변경되면 문서를 일일히 수정해야 하는 번거로움이 있었다. 더군다나 수기로 작성하다보니 휴먼에러가 발생할 수 있어서, FE와 BE의 의사소통이 어려울 수 있으며, 그리고 FE 입장에서 API를 테스트할 수 있는 방식으로 Postman이나 cURL로 직접 URL 및 Request 작성하여 테스트해야한다. 이러한 문제점을 해결하고자 등장한 것이 ? > ## ✨ Swagger ✨

rancho0408

spring 3부터는 swagger ui가 정상적으로 동작하지 않기 때문에 변경이 필요하다 swagger 관련 라이브러리는 implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2' SwaggerConfig.java 파일은 spring-openapi로 변경이 되면서 import도 수정 import io.swagger.v3.oas.annotations.Operation; 기존 어노테이션들도 변경이 필요하다 @Api → @Tag @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden @ApiImplicitParam → @Parameter @ApiImplicitParams → @Parameters @ApiMod

gynhyunkim

Swagger란? 스웨거는 개발자가 REST API 서비스를 설계, 빌드, 문서화하는 도구이다 API가 수정되더라도 문서가 자동으로 갱신된다 API 명세서를 자동화 할 수 있다 Swagger-ui 따로 구현할 필요 없이 API를 시각화하고 resource를 한눈에 보는 것이 가능하다 SpringBoot에 적용하기 Swagger를 스프링 부트 프로젝트에 적용하기 위해 검색해봤다. 보통 springfox를 사용한 글이 많이 나왔는데 springfox는 2020년 이후로 업데이트가 중지되어서 Springboot 3.x.x과는 충돌이 일어나는 일이 많다고 한다. 따라서 springfox가 아닌 springdoc-openapi-ui를 사용했다. 공식 문서를 참고해서 프로젝트에 적용할 수 있었다. Dependency 추가 pom.xml 파일에 의존성을 추가한다. 의존성

kwg527

배경 반환은 List형태인데, 잘못 표기되어서 보여진다 Swagger를 사용해 반환형을 명시해주고 있는데, List형태는 어떻게 명시해주어야 하는지를 몰라서 찾아봤다 변경 이전의 코드는 아래와 같다 내가 한 방법 결론은 @ApiResponse의 content 부분을 수정해주면 해결된다 @ArraySchema를 사용해서 명시해줄 수 있다 적용이 된 것을 확

batlove108

Swagger란? > - RESTful API문서를 자동으로 생성하고 시각화하는 도구 API 개발자와 사용자 모두에게 API의 기능, 엔드포인트, 매개변수, 응답 형식등을 이해하기 쉽게 제공 Swagger 주요기능 API문서 생성 API의 메타데이터를 기반으로 자동으로 api문서를 생성 API의 엔드포인트, 매개변수, 응답형식, 오류코드등을 상세하게 문서화 할 수있다. 시각화 Swgger는 생성된 api문서를 시각적으로 표현 사용자는 웹 인터페이스를 통해 API의 구조와 시능을 쉽게 파악가능 인터랙티브 API테스트 Swagger UI를 사용하여 API테스트 가능 사용자는 API의 엔드포인트와 매개변수를 선택하고 실제 요청을 보내며 응답을

yth1122

NestJS에서 Swagger 모듈을 사용하여 API테스트 및 문서화를 해보았습니다. NestJS 장점 자동 문서 생성: Swagger는 API 코드의 주석 및 메타 데이터를 기반으로 API 문서를 자동으로 생성합니다. 이로써 개발자는 API에 대한 문서를 수동으로 작성할 필요가 없으며, API가 변경될 때 문서를 업데이트하는 작업이 줄어듭니다. UI: Swagger UI를 통해 생성된 문서를 시각적으로 확인할 수 있습니다. 이 UI는 사용자 친화적이며 API 엔드포인트를 테스트하고 호출할 수 있는 기능을 제공합니다. 보안 및 인증 통합: Swagger를 사용하여 API에 보안 및 인증 기능을 추가할 수 있습니다. API 엔드포인트에 대한 액세스 권한 및 인증 메커니즘을 문서

songyuheon

Dependencies 참고 자료 springDoc 접속 URL localhost:Port/swagger-ui/index.html 트러블 슈팅 현재 Swagger 적용 대상 프로그램이 Spring Security Filter를 사용하기에 Localhost:8080에 JWT 토큰 인증 없이는 접근하지 못하였다. 따라서 Spring의 WebSecurityConfig에 Swagger 사용에

devholic

개요 GDG 챌린지를 진행하며, 멘토님께서 프론트와의 협업을 위해 YAML 파일을 통해 스웨거 문서를 작성해보라고 하심과 동시에 백엔드 코드에 스웨거와 관련된 코드가 들어가지 않도록 하기 위한 방법이 어떤 것이 있을까를 고민해보다가 스웨거 허브에서 작성하면 문제를 해결할 수 있겠다는 생각이 들었다. 개인적으로 알게 된 사용 방법들을 잊지 않기 위해 본 글에 기록해보겠다. 기본 코드 우선 기본적으로 스웨거 허브에서 API 문서를 생성하면 아래 사진과 같다. 이 단계까지는 어렵지 않으니 추가적인 설명은 하지 않겠다. 세부 설정 서버 설정 연결할 서버 설정은 다음과 같이 설정할 수 있다. JWT 적용 스웨거에 JWT를 적용하려면

quden04

[ Swagger란? ] > 백엔드 개발에서 Web API를 문서화하기 위한 도구 간단한 설정으로 프로젝트의 API 목록을 웹에서 확인 및 테스트 가능하게 하는 라이브러리이며, RESTful API를 문서화시키고 관리하는 것에 많이 쓰인다. API 문서를 일반 문서로 작성하게 되면 API가 변경될 때마다 문서를 함께 수정해줘야 하는 번거로움이 있는데 SpringBoot 에서 Swagger를 사용해 문서 수정을 자동화할 수 있다. RESTful API를 테스트할 수 있다는 것이 큰 장점. [ Swagger 사용법 ] 1. 의존성 추가 > Swagger 2.9.2 버전 추가, swagger-annotation, swagger-models는 1.5.21 버전을 추가해 2.9.2버전에서 Long 타입의 필수 파라미터에 example이 없는 경우 ""공백이 Long 타입 파라미터에 들어가서 NumberFormatException이 발생하는 것을 방지해준

letskuku

🌱발단 umc에서 진행하는 프로젝트(취트키) 수행 중 있었던 일이다. 프로젝트 수행 기간이 한달 반 남짓으로 다소 짧아 백엔드 파트에서 따로 API 명세서를 작성하지 않고 swagger를 프론트엔드 파트에 제공하기로 했다. 당시 나는 swagger는 사용해본 경험이 있었지만 swagger로 API 명세서를 대신한 적은 없었기 때문에 그러한 결정이 났을 때 굉장히 알쏭달쏭했던 기억이 난다. 알고보니 그렇게 하기도 한다고 하더라... 우리 프로젝트의 경우에도 이러한 결정을 프론트엔드 파트에 전달하자 swagger를 써볼 좋은 기회인 것 같다며 긍정의 반응을 보였다. swagger 세팅은 초기 인프라 설계 및 데브옵스를 주로 담당했던 팀원이 맡아주었다. swagger-ui 화면이 정상적으로 나타나는 것을 확인한 후, 프론트에서 이해가 쉽도록 swagger에서 여러 설명을 추가적으로 보여주는 어노테이션 또한 팀원들이 각자 맡은 API에 적용하였다. 🌳전개 문제는 로그인

postrel63

spring.mvc.pathmatch.matching-strategy=antpathmatcher 추가해주기 application.yml 이라면 >spring: mvc: pathmatch: matching-strategy=antpathmatcher 어떤 이유(다른 라이브러리나 설정 등등)로 인해 경로가 변경되었고 그 영향을 springFox도 받기 때문에 해당 설정을 추가해줘서 다시 기본 동작 방식으로 작동하도록 해주는 방식입니다.

jihoon729

Spring Boot로 Api서버를 만들때, 보기 편하라고 팀원과 이야기해서 API 명세서를 만들었다. 그런데 한 분이 API명세서를 Swagger라는 것으로 상당히 간단하게 만들 수 있다는 이야기를 해 주셨고, 생각난 김에 바로 찾아보고 적용해봤다. 결과는 참패. 적용이 죽어라고 안됐다. 엄청난 사투를 벌이던 중, 뭔가를 발견했다. 많은 Swagger 관련 글, 영상들에서는 springfox 라이브러리를 사용하는 것으로 소개가 되어있다. 여기서 중요한걸 놓쳤다. 그거슨 바로 나의 Spring Boot 버전.. > Spring Boot 3.0.0 이상부터 springdoc-openapi-ui 라이브러리를 사용해야 함 뭔가 잘못됐음을 깨닳았다. <image src="https://velog.velcdn.com/images/jihoon729/post/c1d2b370-2fae-4c53-bc7a-ef63c3bbbca3/image.png" width="7

becooq81

Swagger: Rest API를 자동으로 문서화하여 API 호출 및 테스트 과정을 편리하게 해준다 1. Swagger 의존성 추가 2. Swagger UI 환경설정(config) Docket: Swagger 프레임워크의 핵심 인터페이스로 쓰이는 Java 객체이자 builder useDefaultResponseMessages(boolean) - Swagger에서 제공하는 응답코드(200, 401, 403, 404)에 대한 기분 메시지 사용 여부 groupName(API_VERSION) - 여러 Docket Bean 생성시 충돌을 막기 위해 버전 명시 select() - ApiSelectorBuilder 생성 `apis(RequestHandlerSel

juns1s

Swagger(스웨거) 스웨거는 RestAPI를 위한 OpenAPI스펙에 맞춘 문서화를 도와주는 툴이다. MBTIgram Swagger예시 스웨거를 통해 할 수 있는 것 API 문서화 API 시각화 API 테스트 스프링부트 3.0이상에 적용 build.gradle에 추가하면 즉시 http://localhost:8080/swagger-ui/index.html#/ 에 접속하여 생성된 API문서를 확인할 수 있다. SwaggerConfig.java yaml 설정 어노테이션 1. @Tag 같은 name끼리 같은 API그룹으로 묶을 수 있다. ![](https://velog.velcdn.com/images/juns1s/post/20

whdgnszz1

Nest.js를 사용하여 간단한 서버를 만들어봤다. Nest.js 우선, Nest.js의 모듈 시스템과 의존성 주입 기능은 코드의 재사용성과 확장성을 크게 향상시켜줬다. 또한, 미들웨어, 인터셉터, 가드와 같은 핵심 기능들이 웹 애플리케이션 개발에 큰 도움을 줬다. 처음 배울때에는 정말 어려웠지만 익숙해질수록 편리한 기능들이 너무 많았다. TypeORM 사용 서버를 만들면서 Mongoose를 사용하다가 MySQL을 사용하기 위해 TypeORM으로 변경하는 작업이 있었는데, 각 서비스마다 Repository를 생성하고, Repository의 함수들만 수정해주니 MongoDB에서 MySQL로의 DB변환작업이 끝났다. 느낀점 이외에도 express에선 번거로웠던 swagger 문서 작성이 너무 간편해져서 놀랐고, 객체지향에 대해 공부하는 이유도 알 수 있었다. 그동안 공부했던 DI, IOC 등의 내용이 Nest.js를 직접 사용하면서 조금은 이해된 것 같다.

jegwlee

패키지 설치 main.ts 설정 localhost:3000/api 접속시 SwaggerModule이 자동으로 모든 엔드포인트를 가져온다. 아래같은 @ApiResponse decorator를 상속하는 API response decorator들과 다른 데코레이터들을 DTO, 컨트롤러, 메서드 앞에 붙여주면 된다. @ApiOkResponse() @ApiCreatedResponse() @ApiAcceptedResponse() @ApiNoContentResponse() @ApiMovedPermanentlyResponse() @ApiFoundResponse() @ApiBadRequestResponse() @ApiUnauthorizedResponse() @ApiNotFoundResponse()

steady_aa

기본적으로 SpringSecurity에 403 오류 양식이 존재한다. 근데 그게 마음에 들지 않거나 다르게 만들고 싶을 때 커스터마이징을 진행한다. SpringSecurity에 exceptionHandling을 통해서 오류가 발생시 예외를 따로 처리한다. 추가로 ApiAuthenticationEntryPoint를 만든다. -> 인증 예외가 생길경우 의미가 생기는 클래스 (인증 예외가 발생시 어떻게 할 것인지 결정하게 만듬) 예외가 발생하면 Security에 등록을 통해서 이게 인증예외를 처리함. 원하는 양식이 존재할 경우와 양식을 통일 시키기 위해서 사용된다. 응답 데이터가 rsdata.of 에 넣은것으로 바뀌게 ![](https://velog.velcdn.com/images/ste

steady_aa

Spring Doc 사용 -> 내부적으로 swagger를 사용한다. 실행하고 밑의 주소로 이동하면 자동으로 swagger api 문서가 생성된다. http://localhost:8080/swagger-ui/index.html 단점 get을 호출할경우 403이 나올 수있음 -> header 값을 조정할 수 없어서(header에 토큰 값이 필요한 경우에는 403에러가 발생한다. -> 밑에서 다시 다룰 예정 Swagger 문서 꾸미기 Tag 어노테이션을 통해서 이름을 바꿀수 있고 ,설명을 적어줄 수 있다. 내부에있는 api를 꾸미는 경우 operation 어노테이션으로 내용을 요약해서 알려줄 수있음. 위의 이미지와 같이 api에 어떤 것 이 가능한지를 알

younghwan

express나 Nest.js 같은 웹 프레임워크에서는 요청의 JSON body를 검증하는데 사용할 수 있다. 다음과 같이 class-transformer와 class-validator를 이용해서 라우터나 컨트롤러에 도달하기 전에 요청의 JSON body를 클래스의 인스턴스로 변환한 뒤에 검증할 수 있다. 검증을 위한 다양한 validation option 들을 사용할 수 있다. 이들에 대해서 알아보자. Stripping properties whitelist forbidNonWhitelisted whitelist 의 경우 정의 되지 않은 property 를 제외하고 전달하고 forbidNonWhitelisted 는 정의 되지 않은 property 를 발견하면 에러를

yeonbot

서론 약 1년전, 이직을 위한 면접을 보러 다니던 시기였다. TS를 찍먹만 해보던 시절, 면접 질문에 TS 관련한 내용이 나오면 잘 모르겠다는 답변만 내놓던 시절이 있었다. 그 중 백엔드 API의 Response는 타입 처리를 어떻게 하시나요? 라는 질문에 아는 방법이 없어서 any 처리를 해봤다 라는 답변뿐이 할 수 없었다.(면접은 당연하게도 떨어졌다) 만약 어떤 방법을 써야할지 모르겠다면 이글을 가볍게 읽어 보기 바란다. (1년이 지나서야 쓰는 API response 에 type 적용하기) API의 Response는 타입 처리를 어떻게 하시나요? 결론 부터 말하자면, Swagger의 OPEN API의 명세를 이용해 interface를 자동 생성 하는 방법을 사용한다 swagger, open API란 ? > Swagger 는 REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이되는 OpenAPI 사양을 중심으로 구축 된 오