참고 밸덩 swagger 적용 소개글
참고 [Spring Boot Tutorial] 13. OpenAPI 3.0를 이용한 REST API 문서 만들기 (Swagger v3)
😂 Swagger가 뭔데?
api 프로젝트를 진행하면 api 자동 문서화도 함께 진행하게 된다. 지금까진 spring 에서 추천해주는 restdocs를 사용해왔는데. 회사에서 swagger로 진행해보자는 얘기가 있어서 swagger를 적용시킨 프로젝트를 만들어보려고 한다.
👌 Swagger라 부르고 OpenAPI로 쓴다.
기존의 Swagger로 많이 알려져있는 도구인데 Swagger라는 이름 자체를 버린건 아니고 OpenAPI와 Swagger의 기능을 좀 더 구분지었다고 한다. OpenAPI라는 기능을 통해 restful api를 자동으로 json이나 yml로 표현시키고 그 이외의 Swagger Editor, Swagger UI, Swagger Codegen와 같은 도구들을 Swagger라고 한다고 이해했다.
Swagger Editor 브라우저 기반의 편집기, OpenAPI Spec을 쉽게 작성할 수 있게 도와줌
Swagger UI OpenAPI spec문서를 브라우저에서 확인할 수 있게 해줌, API Test도 가능
Swagger Codegen OpenAPI spec에 맞게 Server나 Client의 stub code생성
참고 OpenAPI 란? (feat. Swagger)
참고 Swagger 공식 블로그 Swagger와 OpenAPI의 차이점
✅ Swagger 적용하기
🔨 의존성 추가
implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.9'gradle에 다음 의존성을 추가해준다.
👏 설정 끝!
이러면 기본 설정은 끝난다. 추가적인 설정이 많이 있지만 기본 화면을 제공하는 것은 위 내용만으로도 충분하다.
이제 서버를 실행시키고 http://localhost:8080/swagger-ui/index.html#/ url로 접근해보자.
내 프로젝트에 conroller 쪽 설정해두었던 url들을 테스트할 수 있도록 변경되었으며 파라미터로 사용되는 Dto들도 설명이 나와있다.
🔨 url 바꿔보자
url 접근하려니 너무 맘에 들지 않는다. url을 변경해서 사용해보자.
#swagger 설정 (OpenApi 3.0)
springdoc:
version: '@project.version@' #project version 표시
api-docs:
path: /api-docs #api docs url 설정
swagger-ui:
path: /api/docs #api ui docs url 설정
paths-to-match:
- /** #문서화할 api url ex) /api/**yml의 경우 다음과 같이 설정하면 해당 url을 입력했을 때 자동으로 리디렉션을 사용하여 연결해준다.
http://localhost:8080/api/docs url로 접근해보자.
이후 설정은 회사나 자신이 원하는 설정을 찾아서 추가해나가면 될것 같다!
🔨 Swagger info 수정하기
현재 swagger 화면에는 다음과 같이 기본 정보가 제공되어지고 있다. 이 정보를 우리가 원하는 정보로 수정해서 사용해보려고 한다.
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
@Component
public class SwaggerConfig {
@Bean
public OpenAPI openAPI(@Value("${springdoc.version}") String appVersion){
Info info = new Info()
.title("타이틀")
.version(appVersion)
.description("API 테스트입니다.")
.termsOfService("http://swagger.io/terms/");
return new OpenAPI().components(new Components()).info(info);
}
}아무 위치에 다음과 같이 SwaggerConfig class를 정의해준다.
그럼 다음과 같이 수정된 화면을 확인할 수 있다!
참고로 Swagger는 2.0에서 3.0으로 버전을 올리면서 좀 많이 수정이된 느낌이다. 문서를 찾아볼 때 자신이 적용한 Swagger의 버전을 확인하고 알맞게 적용하는게 필요할 것 같다. 또한 3.0이 되면서 2.0보다 성능을 개선하고 구조를 단순화 하는데 힘을 쏟았다고 하니 잘 쓸수 있다면 3.0을 쓰는게 더 좋을거 같다!
