OpenAPI & Swagger & Springdoc (1) - 개념 정리

들어가며

---

Swagger에 대해서 알게되어 정보를 찾아보던중 springfox swagger나 springdoc 등 헷갈리게하는 단어들이 계속 등장해서 각각을 정리한다. 무엇이든 개념이 정확히 박혀있어야 이해가 빠르다.

 

OpenAPI Spec

---

OpenAPI Specification (OAS) 은 RESTful API를 기술하는 표준으로 서비스에서 제공하는 API의 기능과 정보를 제공한다.

OAS는 json이나 yml 형식으로 기술해야 하며 OAS 파일을 읽어서 디플로이 해주는 도구를 사용하면 아래와 같이 브라우저에서 UI를 통해 API 문서를 볼 수 있다.

OAS는 예전에는 Swagger spec으로 불렸으며 3.0부터는 OpenAPI 3.0 Specification이라는 이름으로 표준화되었다.

 

 

Swagger란?

---

스웨거란 OAS를 위한 프레임워크이다. API들이 가지고 있는 스펙을 명세, 관리할 수 있는 프로젝트이다. 협업을 진행하는 경우 이미 만들어져 있는 프로젝트에 대한 유지보수를 진행하게 될 때 구축되어 있는 API서버가 어떤 스펙을 가지고 있는지 파악해야디는데 이러한 경우 Swagger를 이용한다. 즉, 스웨거란 개발자가 REST API 서비스를 설계, 빌드, 문서화할 수 있도록 하는 프로젝트이다.

 

Swagger 이용시 장점

---

- API 정보 현행화 가능

- API를 통해 파라미터, 응답 정보, 예제 등 Spec 정보 전달이 용이

- 실제 사용되는 파라미터로 테스트 가능

 

Swagger Tool 종류

---

- Swagger Codegen : Swagger로 정의된대로 클라이언트/서버 코드를 생성하는 CLI 툴이다.

- Swagger UI : Swagger UI는 Swagger API 명세서를 HTML 형식으로 확인할 수 있는 툴이다.

- Swagger Editor : Swagger 표준에 따른 API 설계서/명세서를 작성하기 위한 에디터이다.

 

 

Springfox Swagger & Springdoc

---

Springfox Swagger는 스프링 프레임웤르를 사용하는 프로젝트에서 Swagger를 이용해서 API문서를 쉽게 쓸 수 있도록 도와주는 라이브러리이다.

Springdoc는 Springfox Swagger가 업데이트를 중단한 사이에 나타난 라이브러리이며 마찬가지로 스프링으로 개발시 swagger 문서를 쉽게 작성할 수 있도록 도와주는 라이브러리이다.

 

마치며

다음 시간에는springdoc 사용방법에 대해 정리한다.