공식문서를 읽어보며 swagger를 이해하고 사용하기 위해 필요한 일부 내용을 해석하여 옮겨놓은 글입니다. 필요에 따라 생략되는 내용이 많습니다. 정확한 정보는 같이 적어놓은 공식문서 링크를 참고하세요.
about
Swagger는 팀과 개인을 위한 API 개발자 도구 모음으로 설계 및 문서화에서 테스트 및 배포에 이르기까지 전체 API 수명주기에 걸쳐 개발을 지원합니다.
총 다섯 가지의 주요 기능을 제공하고 있습니다.
- API Design
- API Build
- API Document
- API Test
- API Standardize
Swagger는 2010년에 RESTful API를 설계하기 위한 간단한 오픈 소스 사양(specification)로 시작되었습니다. Swagger UI, Swagger Editor, Swagger Codegen과 같은 오픈소스 도구도 사양에 정의된 API를 더 잘 구현하고 시각화하기 위해 개발되었습니다.
2015년에 SmartBear Software에 인수되었고 Swagger Specification은 Linux 재단에 기부되었으며 OpenAPI로 이름이 변경되었습니다.
현재 Swagger의 서비스는 다음과 같이 운영되고 있습니다.
OpenSource(무료) - Swagger UI, Swagger Editor, Swagger Codegen
Pro(유료) - SwaggerHub(14일 무료), Swagger Inspector, etc.
OpenAPI Specification
Introduction
OpenAPI Specification(OAS)은 RESTful API에 대한 표준, 언어에 구애받지 않는 인터페이스를 정의하여 사람과 컴퓨터 모두 소스 코드, 문서에 액세스하지 않고 또는 네트워크 트래픽 검사를 통해 서비스의 기능을 검색하고 이해할 수 있도록 합니다. 적절하게 정의되면 소비자는 최소한의 구현 로직으로 원격 서비스를 이해하고 상호 작용할 수 있습니다.
그런 다음 문서 생성 도구에서 OpenAPI 정의를 사용하여 API를 표시하고 코드 생성 도구를 사용하여 다양한 프로그래밍 언어로 서버와 클라이언트를 생성하고 테스트 도구 및 기타 많은 사용 사례를 사용할 수 있습니다.
Definitions
OpenAPI Document
API를 정의하거나 설명하는 문서(또는 문서 집합)입니다. OpenAPI 정의는 OpenAPI 사양을 사용하고 준수합니다.
Path Templating
경로 템플릿은 중괄호({})로 구분된 템플릿 표현식을 사용하여 경로 매개 변수를 사용하여 URL 경로의 섹션을 교체 가능으로 표시하는 것을 말합니다.
경로의 각 템플릿 표현식은 경로 항목 자체 그리고/또는 각 경로 항목의 작업에 포함된 경로 매개 변수와 일치해야합니다.
Media Types
미디어 유형 정의는 여러 리소스에 분산되어 있습니다. 미디어 유형 정의는 RFC6838을 준수해야만 합니다.
HTTP Status Codes
HTTP 상태 코드는 실행 된 작업의 상태를 나타내는 데 사용됩니다. 사용 가능한 상태 코드는 RFC7231에 의해 정의되고 등록된 상태 코드는 IANA 상태 코드 레지스트리에 나열됩니다.
Specification
Versions
OpenAPI Specification은 Semantic Versioning 2.0.0 (semver)을 사용하여 버전이 지정되며 semver 사양을 따릅니다.
2.0 또는 3.0.0 버전을 사용할 수 있습니다.
Format
OpenAPI 사양을 준수하는 OpenAPI 문서는 그 자체가 JSON 객체이며 JSON 또는 YAML 형식으로 표시 될 수 있습니다.
- 사양의 모든 필드 이름은 대소 문자를 구분합니다.
여기에는 키가 대소 문자를 구분하지 않는다는 명시 적으로 언급 된 경우를 제외하고 맵에서 키로 사용되는 모든 필드가 포함됩니다. - 스키마는 선언된 이름이 있는 고정 필드와 필드 이름에 대한 정규식 패턴을 선언하는 패턴화된 필드의 두 가지 유형의 필드를 노출합니다.
- 패턴화 된 필드는 포함하는 객체 내에서 고유한 이름을 가져야합니다.
- YAML과 JSON 형식 사이를 왕복하는 기능을 유지하기 위해 YAML 버전 1.2는 몇 가지 추가 제약 조건과 함께 권장됩니다.
- 태그는 JSON 스키마 규칙 세트에서 허용하는 태그로 제한되어야합니다.
- YAML 맵에서 사용되는 키는 YAML Failsafe 스키마 규칙 세트에 정의 된대로 스칼라 문자열로 제한되어야합니다.
참고: API는 YAML 또는 JSON 형식으로 OpenAPI 문서에 의해 정의 될 수 있지만 API 요청 및 응답 본문과 기타 콘텐츠는 JSON 또는 YAML 일 필요가 없습니다.
Document Structure
OpenAPI 문서는 사용자의 재량에 따라 단일 문서로 구성되거나 여러 개의 연결된 부분으로 나눌 수 있습니다. 후자의 경우 JSON 스키마 정의에서 다음과 같이 해당 부분을 참조하기 위해 사양에서 $ref 필드를 사용해야합니다.
루트 OpenAPI 문서의 이름은 openapi.json 또는 openapi.yaml로 지정하는 것이 좋습니다.
Schema
다음 설명에서 필드가 명시적으로 REQUIRED가 아니거나 MUST 또는 SHALL로 설명 된 경우 OPTIONAL로 간주 될 수 있습니다.
OpenAPI Object
OpenAPI 문서의 루트 문서 객체입니다.
Fixed Fields
| Field Name | Type | Description |
|---|---|---|
| openapi | string | REQUIRED. OpenAPI Specification version number |
| info | Info Object | REQUIRED. API에 대한 메타데이터 |
| servers | [Server Object] | 타켓 서버의 연결정보를 담은 서버 객체의 배열. 기본값은 url이 "/"인 서버 객체 |
| path | Paths Object | REQUIRED. API에 사용 가능한 경로 및 작업 |
| components | Components Object | 다양한 스키마를 보유하는 요소 |
| security | [Security Requirement Object] | API에서 사용할 수 있는 보안 메커니즘에 대한 선언 |
| tags | [Tag Object] | 추가 메타 데이터와 함꼐 사양에서 사용하는 태그 목록. 태그 이름은 고유해야 한다. |
| externalDocs | External Documentation Object | 추가 외부 문서 |
