[Swagger] Swagger 2.x VS OpenAPI 3.x

Swagger

• OAS(Open Api Specification)를 위한 프레임워크
• API 문서화를 쉽게 할 수 있도록 도와주며, 파라미터를 넣어서 실제로 어떤 응답이 오는지 테스트 할 수 있습니다.
• 협업 하는 클라이언트 개발자들에게도 Swagger만 전달해주면 API Path와 Request, Response 값 및 제약 등을 한번에 알려줄 수 있습니다.

Swagger 2.x와 OpenAPI 3.x의 관계

SmartBear가 Swagger를 인수했을 때 Swagger 사양을 OpenAPI 2.0으로 이름을 변경했지만, OpenAPI 사양과 함께 동작하는 상용 및 오픈 소스 도구를 참조하기 위해 Swagger라는 이름을 유지했습니다.

• OpenAPI = 사양(Swagger 사양으로 알려진 사양 자체)
• Swagger = 사양 구현을 위한 도구 (OpenAPI 구현에 사용되는 도구)

 

용어

• OpenAPI 문서
  • OpenAPI 사양을 준수하는 JSON 또는 YAML 형식을 사용하여 API를 설명하는 문서
• OpenAPI Initiative(OAI)
  • Linux Foundation 아래에 형성된 산업 컨소시엄
• OpenAPI Specification(OSI : OpenAPI 사양)
  • REST API를 설명하기 위한 산업 표준 언어.

OpenAPI는 OpenAPI Initialtive 하에 제작된 RESTful API 설계 사양. Google, Smartbear, Microsoft 등 IT 총수들이 모여 시작했습니다.

 

재사용성을 높이기 위한 문서 구조 재구성

OpenAPI 3.x에서는 재구성 된 문서 구조를 도입하여 API 정의를 더 쉽게 작성하고 재사용 할 수 있습니다.

OpenAPI 3.x에서는 parameters, responses, request bodies, links와 같이 재사용 가능한 객체인 Components가 포함되었습니다. 뿐만 아니라 Components는 header와 callback 또한 포함하고 있습니다.

 

OpenAPI 3.x 지원 기능

확장된 JSON 스키마 지원

Version 2.x보다 더 많은 JSON 스키마 키워드를 사용할 수 있습니다.

예를 들면 Swagger 2.x에서는 oneOf 나 anyOf 키워드를 지원하지 않지만 OpenAPI 3.x에서는 사용할 수 있습니다.

ex) oneOf, anyOf, allOf

 

쉬운 재사용을 위한 example

샘플은 다양한 목적으로 사용하는 OpenAPI 기능 중 하나입니다.

예를 들면 examples 를 사용하여 mock API server tool 을 만들 수 있는데 OpenAPI 3.x에서는 examples 를 쉽게 재사용 할 수 있습니다.

 

기존에는 JSON이나 YAML 객체를 사용해서만 examples 를 설명할 수 있었지만, 3.x에서는 JSON 문자열을 사용하여 여러 형식을 설명할 수 있습니다.

 

보안 흐름에 대한 변경

2.x 버전보다 OpenAPI 3.x는 더 많은 보안 체계와 전달 형식을 지원합니다.

버전 3.x에서는 all HTTP 보안 체계를 다루는 새로운 http 타입이 추가되었습다.

또한, basic 타입은 http 로 이름을 변경하였습니다.

 

응답 형식 업그레이드

와일드 카드 응답 코드는 각각 개별적으로 정의할 필요 없이 “4xx”에 대한 응답을 정의할 수 있습니다.

 

Type 배열 지원

이전 버전에서는 type에 단일 문자열만 가능 했지만, 3.x 버전부터는 문자열 배열이 될 수 있습니다.

References

[1] https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/

[2] https://blog.stoplight.io/difference-between-open-v2-v3-v31

[3] https://joont92.github.io/openAPI/Swagger와-OAS의-관계/