[GPT Actions] 8. OpenWeatherMap API

달의이성2024-07-19 22:25

이제 우리가 학습한 내용을 바탕으로 더 복잡한 공개 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 requests

Step 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: integer

Step 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의 모든 엔드포인트와 기능을 포함하도록 확장하고, 더 자세한 설명과 예제를 추가하는 것이 좋습니다.