Hoppscotch to OpenAPI Converter 🚀

A powerful Python tool that automatically converts Hoppscotch API collections to OpenAPI 3.0 specifications with intelligent schema inference from request and response data.

📋 Overview

This converter bridges the gap between API testing and API documentation by transforming Hoppscotch collections into production-ready OpenAPI specifications. Perfect for teams who test APIs in Hoppscotch and need to generate client SDKs, documentation, or integrate with OpenAPI-based tools.

Key Features

• ✅ Intelligent Schema Inference - Automatically infers JSON schemas from request bodies AND response data
• ✅ Response Schema Generation - Parses saved responses to create accurate response schemas
• ✅ Multiple Server Support - Extracts and handles multiple server URLs
• ✅ Template Variables - Converts <<ip>>:<<port>> to OpenAPI server variables
• ✅ Complete Parameter Support - Query parameters, headers, and path parameters
• ✅ Type Detection - Automatically detects string, number, boolean, array, and nested object types
• ✅ Nested Structures - Handles complex nested objects and arrays
• ✅ Production Ready - Generates valid OpenAPI 3.0 specs ready for code generation

🚀 Quick Start

Prerequisites

• Python 3.7 or higher
• pip (Python package manager)

Installation

# Clone the repository
git clone https://github.com/yourusername/hoppscotch-to-openapi.git
cd hoppscotch-to-openapi

# Create and activate virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On macOS/Linux
# OR
venv\Scripts\activate     # On Windows

# Install dependencies
pip install -r requirements.txt

Basic Usage

# Convert a Hoppscotch collection to OpenAPI
python3 convert_hoppscotch_to_openapi.py input_collection.json output_spec.yaml

# Example with provided sample
python3 convert_hoppscotch_to_openapi.py agronomy_collection.json api_spec.yaml

Output

✅ Successfully converted agronomy_collection.json to api_spec.yaml
📝 Generated 3 paths

📁 Project Structure

hoppscotch-to-openapi/
├── README.md                           # This file - comprehensive documentation
├── LICENSE                             # Apache 2.0 License
├── CONTRIBUTING.md                     # Contribution guidelines
├── convert_hoppscotch_to_openapi.py   # Main conversion script
├── requirements.txt                   # Python dependencies
├── setup.sh                           # Quick setup script
├── agronomy_collection.json           # Example Hoppscotch collection
├── agronomy_openapi.yaml              # Example converted output
└── examples/                          # Additional examples
    ├── README.md                      # Examples documentation
    ├── simple_get_example.yaml        # GET request example
    └── post_with_body_example.yaml    # POST request example

🔧 How It Works

Input: Hoppscotch Collection

Hoppscotch collections can be exported as JSON or YAML files containing your API requests with saved responses:

{
  "v": 1,
  "name": "My API Collection",
  "requests": [
    {
      "name": "getNurseryType",
      "method": "POST",
      "endpoint": "http://api.example.com/api/v1/getNurseryTypeData",
      "body": {
        "contentType": "application/json",
        "body": "{\"imei\":\"d2b679679b91b8dc\"}"
      },
      "responses": {
        "getNurseryType": {
          "status": "200 OK",
          "code": 200,
          "body": "{\"status\":\"success\",\"data\":[{\"code\":\"N\",\"desc\":\"Normal\"}]}"
        }
      }
    }
  ]
}

Output: OpenAPI 3.0 Specification

The converter generates a complete OpenAPI spec with inferred schemas:

openapi: 3.0.0
info:
  title: My API Collection
  version: 1.0.0
paths:
  /api/v1/getNurseryTypeData:
    post:
      operationId: getNurseryType
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                imei:
                  type: string
                  example: d2b679679b91b8dc
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        desc:
                          type: string

📖 Detailed Usage

Command Line Interface

python3 convert_hoppscotch_to_openapi.py <input_file> <output_file>

Arguments:

• <input_file> - Path to your Hoppscotch collection file (JSON or YAML)
• <output_file> - Path where the OpenAPI specification will be saved (YAML format)

Complete Workflow Example

# 1. Export your collection from Hoppscotch
#    File → Export → JSON or YAML
#    Save as: my_api_collection.json

# 2. Convert to OpenAPI specification
python3 convert_hoppscotch_to_openapi.py my_api_collection.json openapi_spec.yaml

# 3. Validate the generated OpenAPI spec (optional, requires openapi-generator-cli)
npx @openapitools/openapi-generator-cli validate -i openapi_spec.yaml

# 4. Generate client SDK in your preferred language
# Dart/Flutter
npx @openapitools/openapi-generator-cli generate -i openapi_spec.yaml -g dart -o ./dart_client

# TypeScript/Axios
npx @openapitools/openapi-generator-cli generate -i openapi_spec.yaml -g typescript-axios -o ./ts_client

# Python
npx @openapitools/openapi-generator-cli generate -i openapi_spec.yaml -g python -o ./python_client

# Java
npx @openapitools/openapi-generator-cli generate -i openapi_spec.yaml -g java -o ./java_client

🧪 Testing

Test the converter with the example collection:

# Convert example
python3 convert_hoppscotch_to_openapi.py hoppscotch_collection.yaml test_output.yaml

# Validate output
openapi-generator validate -i test_output.yaml

# Should output: "No validation issues detected."

🐛 Troubleshooting

Issue: "ModuleNotFoundError: No module named 'yaml'"

Solution: Install PyYAML

pip install pyyaml

Issue: "FileNotFoundError: [Errno 2] No such file or directory"

Solution: Check that your input file path is correct

ls -la hoppscotch_collection.yaml

Issue: Generated OpenAPI spec has validation errors

Solution: Check your Hoppscotch collection format. Ensure:

• Request bodies are valid JSON
• Endpoints have proper URLs
• Method names are valid (GET, POST, PUT, DELETE, etc.)

Issue: Schema inference is incorrect

Solution: The script infers schemas from examples. If your example doesn't represent the full schema, you may need to manually edit the generated OpenAPI spec.

� Best Practices

• Use descriptive names in Hoppscotch for better operationIds
• Provide complete examples in request bodies for better schema inference
• Validate output before using with code generators

🤝 Contributing

We welcome contributions from the community! This project is open source under the Apache 2.0 License.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/hoppscotch-to-openapi.git
cd hoppscotch-to-openapi

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Make your changes
# ...

# Test your changes
python3 convert_hoppscotch_to_openapi.py examples/post_with_body_example.yaml test_output.yaml

# Validate output
npx @openapitools/openapi-generator-cli validate -i test_output.yaml

📄 License

Copyright 2024 Hoppscotch to OpenAPI Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Hoppscotch Team - For creating an amazing API testing tool
• OpenAPI Initiative - For the OpenAPI Specification
• Contributors - Everyone who has contributed to this project

📞 Support & Community

• Issues - Report bugs or request features via GitHub Issues
• Discussions - Ask questions in GitHub Discussions
• Pull Requests - Contribute code via Pull Requests

🌟 Star History

If you find this project useful, please consider giving it a star ⭐ on GitHub!