OpenAPI 설명 및 JSON 샘플 또는 예시

tilnote2023-11-12 16:27

OpenAPI 란? OpenAPI는 개발자들이 RESTful API 서비스를 정의, 생성, 문서화 및 사용할 수 있게 하는 명세(specification)입니다. (구 Swagger)

이를 통해 API에 대한 정보를 규격화해서 전달하고 받을 수 있습니다. 어떤 라우트를 사용하는지 어떤 값을 필요로 하고 어떤 응답을 하는지를 양식에 맞추어서 적은 것입니다. 실제 예시를 보면서 알아봅시다.

Tip: API란? API는 'Application Programming Interface'의 약자로, 소프트웨어나 시스템이 가진 기능을 외부 프로그램이나 개발자가 사용할 수 있도록 제공하는 매개체입니다.

예시

{
  "openapi": "3.1.0",
  "info": {
    "title": "Weather API",
    "version": "1.0.0",
    "description": "This API provides weather information."
  },
  "paths": {
    "/weather": {
      "get": {
        "summary": "Get weather information",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "example": {
                  "city": "New York",
                  "temperature": 72
                }
              }
            }
          },
          "404": {
            "description": "City not found",
            "content": {
              "application/json": {
                "example": {
                  "error": "City not found"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Submit weather information",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "city": {
                    "type": "string"
                  },
                  "temperature": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Data submitted successfully"
          }
        }
      }
    }
  }
}

OpenAPI는 JSON 또는 YAML 형식으로 작성됩니다.
openapi 필드는 OpenAPI 스펙의 버전을 나타냅니다 (현재 최신 버전은 3.1.0)
info 객체는 API에 대한 정보를 제공합니다 (title, version, description 등).
paths 객체는 API 엔드포인트와 작업을 정의합니다.
각 경로에는 HTTP 메서드(GET, POST, DELETE, PUT 등)와 연결된 작업이 정의됩니다.
작업은 간단한 설명인 summary(필수는 아님)와 GET의 요청 및 응답을 정의하는 parameters 및 responses로 구성됩니다.
parameters는 GET API 요청의 매개변수(Query)를 정의하며, in, name, required, schema 등을 포함합니다.
responses는 API 응답을 정의하며, 상태 코드(예: 200, 404)에 따른 응답 및 예시를 포함합니다.
post 의 경우 requestBody 안에 전송하는 데이터 값을 정의합니다.

이렇게 규격을 정함으로써 규칙에 따라 통신을 할 수 있어요.