API 사양은 표준 형식을 사용하여 API를 설명합니다. 머신에서 읽을 수 있지만 사람도 쉽게 읽고 이해할 수 있습니다. 사양은 일반적으로 그림 1에 표시된 것처럼 기본 경로, 경로 및 동사, 헤더, 쿼리 매개변수, 작업, 콘텐츠 유형, 응답 설명 등과 같은 API 요소를 설명합니다.
그림 1. OpenAPI 사양에서 발췌한 내용
API 버전에는 OpenAPI 사양, Proto, WSDL과 같이 동일하거나 다른 유형의 여러 API 사양이 포함될 수 있습니다. 지원되는 경우 API 허브가 API 사양을 파싱하여 API ID, 버전 ID, 설명, 작업과 같은 API 메타데이터를 추출하고 저장할 수 있습니다. 사양 파싱을 참조하세요.
API 허브에 API 사양 사용
API 사양 유무에 관계없이 API 허브에서 API 버전을 만들 수 있습니다.
버전을 만들 때 사양을 업로드할 수 있습니다. 사용자 인터페이스에서 API 세부정보를 보면 API 리소스의 버전과 관련된 모든 사양 목록이 표시됩니다.
REST API를 사용하여 사양으로 버전을 만들고 구성할 수도 있습니다. API를 사용할 때는 사양으로 API 버전 항목을 만든 후 버전을 API 리소스에 연결합니다.
지원되는 경우 API 허브는 API 사양을 파싱하여 API에 대한 정보를 추출하고 API 버전과 함께 저장할 수 있습니다. 예를 들어 API 허브는 API OpenAPI 사양을 파싱하여 API ID, 버전 ID, 설명, 작업, 기타 메타데이터를 추출하고 저장할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-03(UTC)"],[[["\u003cp\u003eAPI specifications are standardized, machine-readable formats that describe APIs, including elements like paths, verbs, headers, and response descriptions.\u003c/p\u003e\n"],["\u003cp\u003eAPI hub allows the creation of API versions both with and without an API specification, which can be uploaded during version creation or added later using the REST API.\u003c/p\u003e\n"],["\u003cp\u003eAPI hub can parse API specifications, such as OpenAPI, to extract and store API metadata, including the API ID, version ID, description, and operations.\u003c/p\u003e\n"],["\u003cp\u003eAPI hub supports the validation of API specifications, and specification parsing is only available for OpenAPI specifications versions 2.0, 3.0 and 3.1 in both JSON and YAML formats.\u003c/p\u003e\n"]]],[],null,["# Introduction to API specifications\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\nAbout API specifications\n------------------------\n\nAPI specifications use standard formats to describe APIs. They are machine readable, but also\neasy for humans to read and understand. Specifications typically describe elements of an API\nsuch as its base path, paths and verbs, headers, query parameters, operations, content types,\nresponse descriptions, and so on, as shown in Figure 1.\n\n**Figure 1.** Excerpt from an OpenAPI specification.\n\nAn [API version](./versions-intro) can contain multiple API specifications of the same or different types such as\n[OpenAPI Spec](https://swagger.io/specification/), Proto, and WSDL. Where supported, API hub can parse an API specification to extract and store\nAPI metadata, such as the API ID, version ID, description, and operations. See [Specification parsing](#specificationparsing).\n\nUsing API specifications with API hub\n-------------------------------------\n\nYou can create an API version in API hub with or without an API specification.\n\nYou can upload a specification\nat the time you create a version. When you view details of an API in the user interface, you will\nsee a list of any specs that are associated with the versions of an API resource.\n\nYou can also create and configure a version with a specification using the REST API. When\nusing the API, you create an API version entity with the specification, then you can attach the version\nto an API resource.\n\nFor more information, see [Add a spec to a version](./manage-specifications#addspec).\n\nSpecification parsing\n---------------------\n\nWhere supported, API hub can parse an API specification to extract information about the API\nand store it with an API version. For example, API hub can parse an API OpenAPI specification to extract and store\nthe API ID, version ID, description, operations, and other metadata.\n\n\nAPI hub also supports specification validation. See [Validate an API specification](./validate-spec).\n\n| **Note:** API specification parsing is only supported for [OpenAPI specifications](https://swagger.io/specification/) (v.2.0, v3.0 and v3.1) in JSON and YAML formats."]]
