Skip to content

Latest commit

 

History

History

api

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
API_REFERENCE.md
API_REFERENCE.md
 
 
README.md
README.md
 
 
openapi.yaml
openapi.yaml
 
 
postman_collection.json
postman_collection.json
 
 

README.md

API Documentation

Complete API documentation for Meteo Weather App with multiple formats for different use cases.

📚 Available Documentation Formats

1. API_REFERENCE.md - Human-Readable Documentation

Best for: Reading, learning, understanding the API

  • Complete endpoint documentation with examples
  • Request/response payloads in JSON
  • Authentication and rate limiting guides
  • Error handling documentation
  • Searchable markdown format
  • 1,681 lines of comprehensive docs

Start here if you're new to the API!

2. openapi.yaml - OpenAPI 3.0 Specification

Best for: Interactive API exploration, code generation, API tools

Features:

  • Machine-readable API specification
  • OpenAPI 3.0.3 compliant
  • Complete schema definitions
  • Request/response examples
  • Authentication schemes

How to use:

Option A: Swagger UI (Interactive Documentation)

  1. Go to Swagger Editor
  2. Upload openapi.yaml
  3. Click "Try it out" to test endpoints live!

Option B: Swagger UI (Local)

# Install Swagger UI globally
npm install -g swagger-ui-watcher

# Serve API docs
swagger-ui-watcher docs/api/openapi.yaml

# Open http://localhost:8080

Option C: Redoc (Beautiful Documentation)

# Install Redoc CLI
npm install -g redoc-cli

# Generate static HTML
redoc-cli bundle docs/api/openapi.yaml -o api-docs.html

# Open api-docs.html in browser

Option D: Code Generation

Generate client libraries in any language:

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Generate JavaScript client
openapi-generator-cli generate \
  -i docs/api/openapi.yaml \
  -g javascript \
  -o generated/js-client

# Generate Python client
openapi-generator-cli generate \
  -i docs/api/openapi.yaml \
  -g python \
  -o generated/python-client

# Generate TypeScript client
openapi-generator-cli generate \
  -i docs/api/openapi.yaml \
  -g typescript-axios \
  -o generated/ts-client

Supported languages: JavaScript, Python, Java, Go, Ruby, PHP, C#, Swift, Kotlin, and 50+ more!

3. postman_collection.json - Postman Collection

Best for: API testing, development, debugging

Features:

  • All 60+ endpoints included
  • Auto-authentication with test scripts
  • Environment variable management
  • Example requests with realistic data
  • Ready to import into Postman

How to use:

Import into Postman

  1. Open Postman
  2. Click "Import" button
  3. Select docs/api/postman_collection.json
  4. Collection loads with all endpoints!

Set up Environment

Create a Postman environment with these variables:

baseUrl: http://localhost:5001/api (dev) or https://api.meteo-beta.tachyonfuture.com/api (prod)
accessToken: (leave empty - auto-filled after login)
refreshToken: (leave empty - auto-filled after login)

Usage Workflow

  1. Run "Auth > Login" or "Auth > Register" first
  2. Access token auto-populates from response
  3. All subsequent requests use the token automatically
  4. Test any endpoint with example data

Features

  • Auto-authentication: Login sets token for all requests
  • Test scripts: Validate responses automatically
  • Example data: Realistic payloads for testing
  • Organized folders: Endpoints grouped by category

🚀 Quick Start

For API Consumers

1. Start with the human-readable docs:

# Read the API reference
open docs/api/API_REFERENCE.md

2. Test endpoints with Postman:

# Import Postman collection
# File → Import → docs/api/postman_collection.json

3. Generate a client library:

# Generate JavaScript client from OpenAPI spec
openapi-generator-cli generate \
  -i docs/api/openapi.yaml \
  -g javascript \
  -o my-weather-client

For API Developers

1. Update the OpenAPI spec when adding endpoints:

# Edit docs/api/openapi.yaml
paths:
  /your/new/endpoint:
    get:
      tags: [Your Category]
      summary: Your endpoint description
      # ... rest of definition

2. Regenerate documentation:

# Update API_REFERENCE.md manually (or use tooling)
# Update Postman collection (export from Postman)

3. Validate OpenAPI spec:

# Install validator
npm install -g @apidevtools/swagger-cli

# Validate spec
swagger-cli validate docs/api/openapi.yaml

📖 Documentation Comparison

Format Best For Interactive Code Gen Searchable
API_REFERENCE.md Learning, reading ❌ ❌ ✅
openapi.yaml Tools, automation ✅ (via Swagger UI) ✅ ❌
postman_collection.json Testing, debugging ✅ ❌ ✅ (in Postman)

Recommendation:

🔗 API Endpoints Overview

Categories

  • Authentication (6 endpoints) - User registration, login, profile management
  • Weather (4 endpoints) - Current weather, forecasts, alerts
  • Climate Data (5 endpoints) - Historical data, climate normals, records
  • Locations (5 endpoints) - Search, geocoding, reverse geocoding
  • Air Quality (2 endpoints) - AQI data by coordinates or location
  • AI Features (4 endpoints) - AI weather questions, location finder
  • User Preferences (4 endpoints) - Settings, notifications
  • Favorites (4 endpoints) - Saved locations management
  • Cache (3 endpoints) - Cache statistics and management

Total: 37+ documented endpoints (60+ including all variations)

🛠️ Tools & Resources

Interactive Documentation

Code Generation

Validation & Testing

📚 Additional Resources

Related Documentation

External APIs Used

🤝 Contributing

Help us improve the API documentation!

To add new endpoints:

  1. Update openapi.yaml with new endpoint definition
  2. Update API_REFERENCE.md with examples
  3. Add to postman_collection.json
  4. Submit a pull request

To report issues:

⚡ Quick Links

Last Updated: November 7, 2025 API Version: 1.0 Maintained by: Michael Buckingham