Apache ServiceMix

[원문 출처] swagger.io/docs/specification/about/

해당 문서의 경우 SMARTBEAR 사의 Swagger Specirication Document 문서 일부를 번역 한 것입니다. 
번역본인 해당 문서의 경우 역자에게 있음을 알리며 상업적 이용을 불허합니다. 

www.sogomsoft.co.kr (주) 소곰소프트

OpenAPI란 무엇인가?

OpenAPI 규격서 (이전에 Swagger 규격서로 알려진) 는 REST API을 위한 API 설명 서식이다. OpenAPI 파일은 아래를 포함해서 전체 API를 설명하기 위하는 것을 가능하게 한다 :

• 가능한 엔드포인트 (/users 등등) 와 각각의 엔드포인트에서 동작( GET /users, POST /users 등등)
• 각각의 작업을 위한 입력과 출력 작업 파라미터들
• 인증 방법
• 연락처 정보, 라이선스, 사용 약관과 기타 정보.

API 규격서는 YAML 또는 JSON으로 작성 될 수 있고. 이 서식은 쉽게 배울수 있고 개발자와 컴퓨터 양쪽이 읽을 수 있다. 완전한 OpenAPI 규격서는 GitHub에서 볼 수 있다. : OpenAPI 3.0 규격서

Swagger는 무엇인가?

Swagger는  REST API들을 설계하고 빌드하고 문서화하고 소비하는데 도움을 줄 수 있는 OpenAPI 규격서을 중심으로 빌드된 오픈소스 툴 세트이다. 주요 Swagger 툴은 아래를 포함한다. :

• Swagger 편집기 – OpenAPI 규격을 작성 할 수 있는 브라우저 기반의 편집기.
• Swagger 사용자인터페이스 – API 문서와 상호작용함으로써 OpenAPI 규격을 만들어 주는 사용자 인터페이스.
• Swagger 코드생성기 – OpenAPI 규격으로 서버 Stub 또는 클라이언트 라이블러리를 생성기

왜 OpenAPI를 사용하는가?

API 자체의 구조를 기술하는 API들의 능력은 OpenAPI에서 매우 엄청난 것의 뿌리가 된다. 일단 작성되면, OpenAPI 규격서와 Swagger 툴은 다양한 방법에서 더 나은 API 개발 하게 만들 수 있다. :

• 설계-우선 사용자들: 개발 할 API의 서버 Stub을 생성하기 위해 Swagger 코드생성기를 사용한다. 단지 서버 로직을 구현 하는것만 남겨저 있고 이미 사용할 준비가 되어 있다.
• 40개 다른 개발 언어에서 사용할 클라이언트 라이블러리를 생성하기 위해 Swagger 코드생성기를 사용한다.
• 사용자가 브라우저에서 직접 개발한 API 호출을 시도 할 수 있게 하기 위해 API문서와 상호작용을 생성하는 Swagger 사용자인터페이스를 사용한다. 
• 개발된 API에 API 관련 툴을 접속하기 위한 규격으로 사용한다. 예를들면, API에 자동화된 테스트 생성을 위해 SoapUI에 규격을 불러들인다. 
• 그리고 추가로! Swgger와 통합된 open-source 와 commercial tools 을 확인해 보라.