Generate Swagger (OpenAPI) Specification from apis.json #235
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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:
```yaml
# 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 nasa#16.
Create nasa_openapi.yaml
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
/apod)/mars-photos)/neo-feed,/neo-lookup/{asteroid_id})/earth,/gibs,/gibs/layers)/analyze-image)Comprehensive Schema Definitions: Includes detailed request/response schemas with proper validation, constraints, and examples for all parameters and response formats.
Standards Compliance:
Integration Ready: The specification can be immediately used with:
Implementation Details
The specification maps each existing MCP tool function to corresponding REST endpoints:
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:
openapi-spec-validatorAdditional Files
OPENAPI_README.md: Comprehensive documentation explaining usage, integration options, and validation procedures.gitignore: Updated to exclude generated files and temporary validation scriptsThis 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 #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)