Generate Swagger (OpenAPI) Specification from apis.json

[adithya1012]

This PR adds a comprehensive OpenAPI 3.1 specification that documents all NASA API endpoints exposed through the MCP server, enabling integration with standard API documentation and tooling.

Overview

The main deliverable is nasa_openapi.yaml, a complete OpenAPI specification that transforms the existing MCP (Model Context Protocol) tools into documented REST API endpoints. This specification provides standardized documentation for all NASA API functionality including astronomy images, Mars rover photos, near-earth objects, Earth imagery, and satellite data.

Key Features

Complete API Documentation: Documents 14 endpoints covering all NASA APIs mentioned in the requirements:

• Astronomy Picture of the Day (/apod)
• Mars Rover Photos (/mars-photos)
• Near Earth Objects (/neo-feed, /neo-lookup/{asteroid_id})
• Earth Imagery (/earth, /gibs, /gibs/layers)
• Image Analysis (/analyze-image)
• Future endpoints: Technology Transfer, Mars Weather, Solar Activity, Natural Events

Comprehensive Schema Definitions: Includes detailed request/response schemas with proper validation, constraints, and examples for all parameters and response formats.

Standards Compliance:

• OpenAPI 3.1.0 specification
• JSON Schema compatible
• RESTful design principles
• NASA API key authentication support

Integration Ready: The specification can be immediately used with:

• Swagger UI for interactive documentation
• Postman for API testing and collection generation
• OpenAPI generators for client SDK creation
• Documentation tools like Redoc

Implementation Details

The specification maps each existing MCP tool function to corresponding REST endpoints:

# Example: APOD endpoint with comprehensive parameter validation
/apod:
  get:
    summary: Get Astronomy Picture of the Day
    parameters:
      - name: date
        schema:
          type: string
          format: date
          example: "2023-12-01"
      - name: api_key
        schema:
          type: string
          default: DEMO_KEY

All parameter types, constraints, and validation rules are extracted from the original MCP function signatures and properly documented with examples and descriptions.

Validation

The specification has been thoroughly validated using:

• YAML syntax validation
• OpenAPI 3.1 specification compliance via openapi-spec-validator
• Custom test suite ensuring all MCP functions are properly mapped
• Parameter validation against function signatures

Additional Files

• OPENAPI_README.md: Comprehensive documentation explaining usage, integration options, and validation procedures
• .gitignore: Updated to exclude generated files and temporary validation scripts

This OpenAPI specification enables the NASA MCP Server to be documented and integrated using standard API tooling while maintaining compatibility with the existing MCP implementation.

Fixes https://github.com/nasa/api-docs/issues/234

More : NASA-MCP-server : https://github.com/adithya1012/NASA-api-docs Pypi package: https://pypi.org/project/nasa-mcp-server/

This work supported by Medical Informatics Engineering (MIE)