OpenAPI Spec 의 최종 버전은 3.1 이며 


스펙

Version 

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


Format

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


Document structure

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


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

Data Type

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

typeformatComments
integerint32signed 32 bits
integerint64signed 64 bits (a.k.a long)
numberfloat
numberdouble
stringpasswordA hint to UIs to obscure input.


Schema

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

Info Object

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

OpenAPI-Specification/3.1.0.md at main · OAI/OpenAPI-Specification (github.com)


nametypeDescription
titlestringREQUIRED. The title of the API.
versionstringREQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).
summarystringA short summary of the API.
descriptionstringA description of the API. CommonMark syntax MAY be used for rich text representation.


Operation Object

OpenAPI-Specification/3.1.0.md at main · OAI/OpenAPI-Specification (github.com)

Field NametypeDescription
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.
summarystringA short summary of the API.
descriptionstringA description of the API. CommonMark syntax MAY be used for rich text representation.
operationIdstringUnique 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.




SecurityScheme

OpenAPI-Specification/3.1.0.md at main · OAI/OpenAPI-Specification (github.com)



carbon.now.sh



Ref





blog comments powered by Disqus