OpenAPI와 Swagger

OpenAPI와 Open API

1. Open API

단어 그대로 “개방된 API”입니다. 즉, 누구나 사용될 수 있도록 API의 endpoint가 개방되어 있다면 Open API입니다. 예를 들어, 기상청의 단기예보 조회API, 우체국의 우편번호 API 등이 있고 Public API라고도 부릅니다.

2. OpenAPI

OpenAPI 는 의미가 완전 다릅니다. OpenAPI 또는 OpenAPI Specification(OAS)라고 부르는데, 이는 RESTful API를 기 정의된 규칙에 맞게 API spec을 json이나 yaml로 표현하는 방식을 의미합니다. 직접 소스코드나 문서를 보지 않고 서비스를 이해할 수 있다는 장점을 가지고 있습니다.

즉, RESTful API 디자인에 대한 정의(Specification) 표준이라고 생각하시면 될 것 같습니다.

 

예전에는 Swagger 2.0와 같은 이름으로 불렸다가 현재는 3.0버전으로 올라오면서 OpenApi 3.0 Specification으로 칭하게 되었습니다.

 

스페이스 바 하나 차이로 의미가 달라지기 때문에 주의해야 할것 같습니다.

 

Swagger

2010년대 초 Tam Wordnik이라는 사람이 개발하기 시작했습니다. 처음에는 모든걸 포함하는 방법론이 아니라, Wordnik(회사) 자체 API용 UI로 개발되었고 2015년초에 SmartBear라는 회사에서 Swagger를 인수했습니다.

그리고 2015년 말, SmartBear는 Linux Foundation의 후원으로 OpenAPI Initiative에 Swagger를 기부하면서 OpenAPI Specification으로 이름이 변경되었습니다. 하지만 현재도 여전히 Swagger는 사용되는 용어입니다.

 

직금의 Swagger는 이전에 Swagger Specification으로 알려진 Specification 자체 (RESTful API 디자인에 대한 정의)인 OpenAPI를 Implement하기 위한 도구입니다.

 

Swagger ui

이런식으로, OpenAPI Specification을 json또는 yaml로 기술한 문서를 swagger-ui를 통해 띄우게되면 브라우저에서 편리하게 API문서를 볼 수 있습니다.

 

Swagger 도구

• Swagger Editor : 브라우저 기반의 편집기, OpenAPI Spec을 쉽게 작성할 수 있게 도와줍니다.
• Swagger UI : OpenAPI spec문서를 브라우저에서 확인할 수 있게 해줌, API Test도 가능합니다.
• Swagger Codegen : OpenAPI spec에 맞게 Server나 Client의 stub code생성합니다.

 

OpenAPI 2.0 vs OpenAPI 3.0Permalink

2015년 Swagger Specification을 OpenAPI Initiative에 기부하면서 OpenAPI Specification(OAS)로 명칭이 바뀌었고, 그 이후 첫번째 major release가 OAS3.0입니다.

 

2.0때보다 구조가 더 단순해졌고, 재사용성이 증가될 수 있도록 개발되었습니다.

 

 

 

Reference

호롤리한 하루