OpenAPI(Swagger) 주요 Spec

스펙

API 버전은 major.minor.patch 형식으로 기술하며 patch 버전은 생략해도 됩니다. 버전

OpenAPI spec 은 JSON 또는 Yaml 형식으로 기술하며 모든 필드는 대소문자를 구분합니다.

OpenAPI document 는 작성자의 재량에 따라 하나의 문서 또는 여러 개로 문서로 분리할 수 있습니다. 여러 개로 분리할 경우 Reference Object 나 Schema Object 의 $ref 를 사용해서 연결할 수 있습니다.

최상의 문서 파일은 openapi.json 이나 openapi.yml 파일로 하는 것을 권장합니다.

data type은 format modifier 속성을 가질 수 있습니다.

스키마중에 많이 사용하는 Object 만 추렸습니다.

API 의 메타 정보를 제공하며 한 API 에 Info 는 하나만 존재해야 합니다.

name	type	Description
title	string	REQUIRED. The title of the API.
version	string	REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).
summary	string	A short summary of the API.
description	string	A description of the API. CommonMark syntax MAY be used for rich text representation.

Field Name	type	Description
tags	[string]	A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
summary	string	A short summary of the API.
description	string	A description of the API. CommonMark syntax MAY be used for rich text representation.
operationId	string	Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.