GPT ACTIONS
[GPT Actions] 8. OpenWeatherMap API
이제 우리가 학습한 내용을 바탕으로 더 복잡한 공개 API를 문서화해보겠습니다. 이번에는 "OpenWeatherMap" API를 예로 들어 진행하겠습니다. 이 API는 전 세계의 날씨 정보를 제공합니다.
Step 1: 기본 구조 설정
openapi: 3.1.0
info:
title: OpenWeatherMap API
description: Access current weather data for any location including over 200,000 cities
version: 2.5.0
termsOfService: https://openweathermap.org/terms
contact:
name: OpenWeatherMap API
url: https://openweathermap.org/api
servers:
- url: https://api.openweathermap.org/data/2.5
description: Production server
tags:
- name: weather
description: Weather data operations
- name: forecast
description: Forecast data operations
paths:
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: appid
security:
- ApiKeyAuth: []Step 2: 경로(Paths) 정의
paths:
/weather:
get:
summary: Get current weather data
tags:
- weather
parameters:
- name: q
in: query
description: City name, state code and country code divided by comma, use ISO 3166 country codes
schema:
type: string
- name: lat
in: query
description: Latitude
schema:
type: number
- name: lon
in: query
description: Longitude
schema:
type: number
- name: units
in: query
description: Units of measurement. standard, metric and imperial units are available
schema:
type: string
enum: [standard, metric, imperial]
default: standard
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/WeatherResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Not found
'429':
description: Too many requests
/forecast:
get:
summary: Get 5 day weather forecast
tags:
- forecast
parameters:
- name: q
in: query
description: City name, state code and country code divided by comma, use ISO 3166 country codes
schema:
type: string
- name: lat
in: query
description: Latitude
schema:
type: number
- name: lon
in: query
description: Longitude
schema:
type: number
- name: units
in: query
description: Units of measurement. standard, metric and imperial units are available
schema:
type: string
enum: [standard, metric, imperial]
default: standard
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ForecastResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Not found
'429':
description: Too many requestsStep 3: 스키마(Schemas) 정의
components:
schemas:
WeatherResponse:
type: object
properties:
coord:
$ref: '#/components/schemas/Coordinates'
weather:
type: array
items:
$ref: '#/components/schemas/WeatherCondition'
base:
type: string
main:
$ref: '#/components/schemas/MainWeatherData'
visibility:
type: integer
wind:
$ref: '#/components/schemas/Wind'
clouds:
$ref: '#/components/schemas/Clouds'
dt:
type: integer
sys:
$ref: '#/components/schemas/Sys'
timezone:
type: integer
id:
type: integer
name:
type: string
cod:
type: integer
ForecastResponse:
type: object
properties:
cod:
type: string
message:
type: integer
cnt:
type: integer
list:
type: array
items:
$ref: '#/components/schemas/ForecastItem'
city:
$ref: '#/components/schemas/City'
Coordinates:
type: object
properties:
lon:
type: number
lat:
type: number
WeatherCondition:
type: object
properties:
id:
type: integer
main:
type: string
description:
type: string
icon:
type: string
MainWeatherData:
type: object
properties:
temp:
type: number
feels_like:
type: number
temp_min:
type: number
temp_max:
type: number
pressure:
type: integer
humidity:
type: integer
Wind:
type: object
properties:
speed:
type: number
deg:
type: integer
Clouds:
type: object
properties:
all:
type: integer
Sys:
type: object
properties:
type:
type: integer
id:
type: integer
country:
type: string
sunrise:
type: integer
sunset:
type: integer
ForecastItem:
type: object
properties:
dt:
type: integer
main:
$ref: '#/components/schemas/MainWeatherData'
weather:
type: array
items:
$ref: '#/components/schemas/WeatherCondition'
clouds:
$ref: '#/components/schemas/Clouds'
wind:
$ref: '#/components/schemas/Wind'
visibility:
type: integer
pop:
type: number
sys:
type: object
properties:
pod:
type: string
dt_txt:
type: string
City:
type: object
properties:
id:
type: integer
name:
type: string
coord:
$ref: '#/components/schemas/Coordinates'
country:
type: string
population:
type: integer
timezone:
type: integer
sunrise:
type: integer
sunset:
type: integerStep 4: 예제(Examples) 추가
components:
schemas:
WeatherResponse:
# ... (이전 내용 유지)
example:
coord:
lon: 10.99
lat: 44.34
weather:
- id: 501
main: "Rain"
description: "moderate rain"
icon: "10d"
base: "stations"
main:
temp: 298.48
feels_like: 298.74
temp_min: 297.56
temp_max: 300.05
pressure: 1015
humidity: 64
sea_level: 1015
grnd_level: 933
visibility: 10000
wind:
speed: 0.62
deg: 349
gust: 1.18
rain:
"1h": 3.16
clouds:
all: 100
dt: 1661870592
sys:
type: 2
id: 2075663
country: "IT"
sunrise: 1661834187
sunset: 1661882248
timezone: 7200
id: 3163858
name: "Zocca"
cod: 200이 OpenAPI 스키마는 OpenWeatherMap API의 주요 기능을 문서화하고 있습니다. 여기에는 현재 날씨 조회와 5일 예보 조회 두 가지 주요 엔드포인트가 포함되어 있으며, 각 엔드포인트에 대한 파라미터, 응답 스키마, 그리고 가능한 응답 코드들이 정의되어 있습니다.
이 스키마를 사용하면 개발자들이 API를 쉽게 이해하고 사용할 수 있습니다. 또한 Swagger UI나 다른 OpenAPI 호환 도구를 통해 대화형 문서를 생성하고 API를 직접 테스트해볼 수 있습니다.
실제 API 문서화 작업을 할 때는 이러한 구조를 기반으로 하되, API의 모든 엔드포인트와 기능을 포함하도록 확장하고, 더 자세한 설명과 예제를 추가하는 것이 좋습니다.
