[Document] springdoc-openapi

 

작성자: 코드몬스터
번역: ChatGPT
참고 사이트: https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/

 

 

Rest API 문서 작업을 위해 검색하면 아래와 같은 여러 단어 나온다.

 

Swagger, openAPI, springdoc, springfox 등등..

 

블로그를 찾아보면 Swagger 사용방법이라는 제목의 글이 나오고 해당 글 안에는 잘 못된 정보가 많은 것 같다.
(사용 방법이 잘 못 됐다는 것은 아니다.)

그리고 프로젝트에 적용한 라이브러리 이름만 봐도 swagger라는 단어는 없다. 즉, swagger 사용방법이 아니다.

 

결론은 다른 기술인데 각 기술의 기반 기술이 swagger이다.

 

---

https://swagger.io/

History

1. 여러 회사를 거쳐 Reverb 라는 회사로부터 SmartBear가 Swagger를 인수했다.
2. SmartBear는 OpenAPI Initiative를 만들고 기부(오픈)했다.
3. 여러 회사가 OpenAPI Initiative의 회원으로 계속해서 기술 발전을 이끌고 있다.

Swagger라고 검색해서 나오는 사이트 이미지에 보면 supported by SMARTBEAR 라고 되어있다.

 

Swagger와 OpenAPI의 차이점

• OpenAPI = 사양 (Specification)
• Swagger = 사양을 구현하기 위한 도구 (Tools for implementing the specification)

즉, Swagger는 OpenAPI 사양을 구현하기 위해 널리 사용되는 가장 잘 알려진 도구들 중 일부와 연관된 이름이다.

 

Swagger 도구 셋

• Swagger Editor: Swagger Editor lets you edit OpenAPI specifications in YAML inside your browser and to preview documentations in real time.
• Swagger UI: Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from an OAS-compliant API.
• Swagger Codegen: Allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec.
• Swagger Parser: Standalone library for parsing OpenAPI definitions from Java
• Swagger Core: Java-related libraries for creating, consuming, and working with OpenAPI definitions
• Swagger Inspector (free): API testing tool that lets you validate your APIs & generate OpenAPI definitions from an existing API
• SwaggerHub (free and commercial): API design and documentation, built for teams working with OpenAPI.

왜 Swagger 도구를 OpenAPI로 변경하지 않았을까?

• Swagger 도구들은 OpenAPI 사양이 되기 전부터 사양과 함께 사용되었던 핵심 오픈 소스 도구들로 구성되어 있었다.
  • Swagger UI, Swagger Editor, Swagger Codegen 등
• SmartBear가 사양을 기부했지만, 인기 있는 오픈 소스 Swagger 도구들은 개발자, 기술 작가, 테스터, 디자이너들과의 강한 연관성 덕분에 원래의 브랜드를 유지했다.
• Swagger를 기부하고 OpenAPI Initiative를 형성한 결정은 OpenAPI가 완전히 벤더 중립적인 상태를 유지하기 위한 것이다.

---

restdocs와 springdoc-openapi 차이점

Springfox와 springdoc-openapi는 오픈 소스 커뮤니케이션에서 만든 Spring 애플리케이션 API 문서를 생성하기 위해 사용되는 라이브러리이다.

 

오픈 소스 커뮤니티의 springdoc-oepnapi 라이브러리

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0")

 

spring boot에서 지원하는 restdocs 라이브러리

testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc")

springdoc-openapi

• springdoc-openapi v1.8.0
  • the latest Open Source release supporting Spring Boot 2.x and 1.x.
• springdoc-openapi v2.6.0
  • is supporting Spring-boot v3 (Java 17 & Jakarta EE 9) and OpenAPI 3, Swagger-ui, OAuth 2

참고사이트

• https://springdoc.org