OpenAPI 사양이란?

이전에 Swagger라고도 하는 OpenAPI 사양은 API의 다양한 측면을 설명합니다. OpenAPI 사양(사양)은 API의 엔드포인트, 매개 변수 및 응답을 설명합니다. OpenAPI 사양은 YAML 또는 JSON으로 작성되며 도구에서 설명서, 테스트 사례 및 클라이언트 라이브러리를 생성하는 데 사용됩니다. API 작성기는 OpenAPI 사양을 사용하여 API가 정확하게 설명되고, 접근성이 높으며, 다양한 애플리케이션 및 서비스에 통합하기 쉽도록 할 수 있습니다.

API에 대해 OpenAPI 사양을 고려해야 하는 이유는 다음과 같습니다.

• 표준화된 방식으로 API를 문서화합니다. 일관되고 사람이 읽을 수 있는 형식으로 API 사양을 문서화합니다.
• 클라이언트 SDK를 생성합니다. Kiota와 같은 도구를 사용하여 다양한 프로그래밍 언어로 클라이언트 라이브러리 생성을 자동화합니다.
• 모의 API를 만듭니다. 실제 API가 아직 구현되지 않은 경우 개발 초기 단계에서 도움이 되는 API 사양에 따라 모의 서버를 만듭니다.
• 협업을 개선합니다. 다른 팀(프런트 엔드, 백 엔드, QA)에 API의 기능 및 제한 사항을 명확하게 이해하여 새 팀 구성원이 신속하게 파악할 수 있도록 합니다.
• 테스트 및 유효성 검사를 간소화합니다. 사양에 대한 API 요청 및 응답의 유효성 검사를 자동화하여 불일치를 보다 쉽게 식별할 수 있습니다.
• API 관리 도구와 통합합니다. Azure API Center 및 Azure API Management와 같은 많은 API 관리 도구 및 게이트웨이를 사용하여 API를 쉽게 통합, 배포 및 모니터링할 수 있습니다.
• API 게이트웨이 구성을 간소화합니다. OpenAPI 사양을 사용하여 API 게이트웨이를 구성하고 라우팅, 변환 및 원본 간 리소스 공유 설정과 같은 작업을 자동화합니다.

OpenAPI 사양을 사용하면 잘 디자인되고 일관되게 문서화된 API를 만들 수 있습니다. 또한 내부 및 외부 소비자 둘 다에서 더 유지 관리가 가능하고 쉽게 사용할 수 있습니다.

OpenAPI 사양이 아직 없나요?

이미 존재하는 API에 대한 사양을 직접 작성하는 데는 시간이 걸리며 API가 실제로 수행하는 작업에서 벗어나게 됩니다. 또 다른 옵션은 API가 반환하는 내용을 기록하고 이를 바탕으로 사양을 생성하는 것입니다.

Approach	얻을 수 있는 것	주의할 사항
손으로 작성하세요	설명 및 예제에 대한 완전한 제어	시간이 걸리고 실제 API와 점점 달라집니다.
코드 어노테이션에서 생성	코드와 동기화된 상태로 유지되는 사양	API의 코드에 액세스해야 하며 프레임워크가 이를 지원해야 합니다.
기록된 트래픽에서 이를 생성하기	직접 소유하지 않은 것까지 포함해 호출할 수 있는 모든 API에 대한 사양	기록된 요청만 다루므로 필요한 API 부분을 사용하거나 테스트하세요.

Dev Proxy는 앱과 API 간의 요청 및 응답을 기록하고 해당 요청 및 응답으로부터 OpenAPI 사양을 생성합니다. 단계는 OpenAPI 사양 생성을 참조하세요.

다음 단계

OpenAPI 사양 생성