couchdb-openapi-scheme-generator 1.2.0

CouchDB OpenAPI scheme generator

🚀 CouchDB OpenAPI Scheme Generator

OpenAPI specification generator for CouchDB - Perfect for developing and debugging applications using CouchDB as a backend

---

📋 Table of Contents

• 🚀 CouchDB OpenAPI Scheme Generator
  • 📋 Table of Contents
  • ✨ Features
  • 🎯 Description
    • 📋 Supported API Endpoints
  • 📦 Requirements
  • 🚀 Quick Start
    • Option 1: Using uvx (Recommended - No Installation Required)
    • Option 2: Install from PyPI
    • Option 3: Development Setup
  • 💻 Installation
    • 📦 Install from PyPI
      • Using pip
      • Using uv
      • Using pipx (Isolated Installation)
    • 🚀 Using uvx (No Installation Required)
    • 🔧 Development Installation
  • 📖 Usage
    • 🐳 Starting CouchDB
    • 📄 Generating OpenAPI Specification
      • Method 1: Using uvx (Recommended)
      • Method 2: Using Installed Package
      • Method 3: Development Mode
      • 📋 Parameters
      • 📚 Generated Specification
    • 🎮 Running the Application
  • 🏗️ Project Structure
  • 🛠️ Development
    • Setting Up Development Environment
    • Code Style
  • 🤝 Contributing
    • Contribution Guidelines
  • 📝 License
  • ⭐ Show Your Support
    • Made with ❤️ by SasukeSagara
      • ⭐ Star this repo if you find it useful! ⭐

---

✨ Features

Feature	Description	Status
🐳 Docker Support	Quick CouchDB deployment with Docker Compose	✅ Ready
📄 OpenAPI 3.0	Modern OpenAPI specification generator	✅ Ready
🔧 CLI Tool	Easy-to-use command-line interface	✅ Ready
📊 JSON/YAML	Support for both JSON and YAML output formats	✅ Ready
🔐 Authentication	Optional authentication support (most endpoints are public)	✅ Ready
⚡ Fast Setup	Get started in minutes	✅ Ready
📚 Comprehensive API Coverage	Full coverage of CouchDB API endpoints according to official documentation	✅ Ready
🎯 Server Endpoints	Complete server management endpoints (tasks, cluster, nodes, etc.)	✅ Ready
🗄️ Database Operations	Full database management (shards, security, compaction, etc.)	✅ Ready
📝 Design Documents	Complete design document endpoints (views, search, show, list, update)	✅ Ready
🔀 Partitioned Databases	Support for partitioned database operations	✅ Ready
📋 Local Documents	Support for local (non-replicating) documents	✅ Ready

---

🎯 Description

This project has been updated for more convenient work with CouchDB and includes:

• 🐳 Updated Docker Compose configuration for quick CouchDB deployment
• 📄 Modern OpenAPI specification generator for CouchDB API
• 🛠️ Utilities and tools for interacting with the CouchDB server
• 🚀 Production-ready setup with best practices
• 📚 Comprehensive API coverage - The OpenAPI specification includes all major CouchDB API endpoints according to the official CouchDB documentation

📋 Supported API Endpoints

The generated OpenAPI specification includes comprehensive coverage of CouchDB API:

• Server Endpoints (18+ endpoints): Server information, active tasks, cluster setup, database updates, membership, scheduler, node management, statistics, Prometheus metrics, UUID generation, resharding, and more
• Database Endpoints (20+ endpoints): Database operations, design documents, bulk operations, indexes, shards, compaction, security, purging, revision management, and more
• Document Endpoints: Full CRUD operations for documents and attachments
• Design Document Endpoints (12+ endpoints): Views, search indexes, nouveau indexes, show/list/update functions, URL rewriting, and more
• Partitioned Database Endpoints (5 endpoints): Partition information, queries, and views
• Local Documents Endpoints (3 endpoints): Local document operations (non-replicating)
• User Endpoints: User management in the _users database

---

📦 Requirements

• 🐍 Python 3.11 or higher
• 📦 Package manager (optional): pip, uv, pipx, or uvx

---

🚀 Quick Start

Option 1: Using uvx (Recommended - No Installation Required)

# Generate OpenAPI specification directly without installation
uvx couchdb-openapi-scheme-generator

That's it! 🎉 Your OpenAPI specification will be generated in couchdb-openapi.json

Option 2: Install from PyPI

# Install using pip
pip install couchdb-openapi-scheme-generator

# Or using uv
uv pip install couchdb-openapi-scheme-generator

# Or using pipx (for isolated installation)
pipx install couchdb-openapi-scheme-generator

# Then run
couchdb-openapi-scheme-generator

Option 3: Development Setup

# 1. Clone the repository
git clone https://github.com/SasukeSagara/CouchDB-OpenAPI-scheme-generator.git
cd couchdb-openapi-scheme-generator

# 2. Install dependencies
uv sync

# 3. Run the generator
uv run openapi_generator.py

---

💻 Installation

📦 Install from PyPI

The package is available on PyPI. You can install it using any Python package manager:

Using pip

pip install couchdb-openapi-scheme-generator

Using uv

uv pip install couchdb-openapi-scheme-generator

Using pipx (Isolated Installation)

pipx install couchdb-openapi-scheme-generator

🚀 Using uvx (No Installation Required)

You can use the package directly without installation using uvx:

uvx couchdb-openapi-scheme-generator

This will automatically download and run the latest version from PyPI.

🔧 Development Installation

If you want to contribute or modify the code:

# 1. Clone the repository
git clone https://github.com/SasukeSagara/CouchDB-OpenAPI-scheme-generator.git
cd couchdb-openapi-scheme-generator

# 2. Install dependencies using uv
uv sync

# For development dependencies
uv sync --dev

---

📖 Usage

🐳 Starting CouchDB

Start CouchDB using Docker Compose:

docker-compose up -d

CouchDB will be available at http://localhost:5984

⚠️ Important: Change the password in .env before using in production!

📄 Generating OpenAPI Specification

Generate the OpenAPI specification for CouchDB API using one of the following methods:

Method 1: Using uvx (Recommended)

# Basic usage (local server, no authentication required)
uvx couchdb-openapi-scheme-generator

# With URL specified (authentication optional)
uvx couchdb-openapi-scheme-generator \
  --url http://localhost:5984

# With URL and credentials (only if server requires authentication)
uvx couchdb-openapi-scheme-generator \
  --url http://localhost:5984 \
  --username admin \
  --password your_password

# With custom output file
uvx couchdb-openapi-scheme-generator --output couchdb-api.json

# Generate in YAML format
uvx couchdb-openapi-scheme-generator \
  --format yaml \
  --output couchdb-api.yaml

Method 2: Using Installed Package

If you installed the package using pip, uv, or pipx:

# Basic usage (no authentication required for most servers)
couchdb-openapi-scheme-generator

# With URL only
couchdb-openapi-scheme-generator --url http://localhost:5984

# With all options (authentication only if required)
couchdb-openapi-scheme-generator \
  --url http://localhost:5984 \
  --username admin \
  --password your_password \
  --format json \
  --output my-couchdb-api.json

Method 3: Development Mode

If you cloned the repository and installed dependencies:

# Using uv run
uv run openapi_generator.py

# Or directly with Python
python openapi_generator.py

📋 Parameters

Parameter	Short	Description	Default
--url	-u	CouchDB server URL	http://localhost:5984
--username	-	Username for authentication (optional)	-
--password	-	Password for authentication (optional)	-
--output	-o	Output file name	couchdb-openapi.json
--format	-f	Output format (json or yaml)	json

💡 Note: Authentication is optional for most operations. The generator first attempts to connect without authentication, as most CouchDB endpoints (including server info) are publicly accessible. If your server requires authentication, you can provide credentials using --username and --password parameters.

📚 Generated Specification

The generated OpenAPI specification includes:

• ✅ 60+ API endpoints covering all major CouchDB operations
• ✅ Complete request/response schemas for all endpoints
• ✅ Query parameters and path parameters properly documented
• ✅ Authentication support via Basic Auth (optional - most endpoints are public)
• ✅ Error responses with appropriate HTTP status codes
• ✅ Compatible with Swagger UI, Postman, Insomnia, and other OpenAPI tools

📝 Important: Most of the information in the OpenAPI specification is statically defined and does not require a connection to the CouchDB server. The generator only queries the server to retrieve the CouchDB version for inclusion in the specification metadata. If the server is not accessible or requires authentication, you can still generate a complete specification (version will be set to "unknown").

The specification is based on the official CouchDB API documentation and includes endpoints for:

• Server management and monitoring
• Database operations and administration
• Document CRUD operations
• Design documents and views
• Search and indexing
• Partitioned databases
• Local documents
• User management

🎮 Running the Application

After installation, you can run the generator using:

# If installed via pip/pipx/uv
couchdb-openapi-scheme-generator

# Or using uvx (no installation needed)
uvx couchdb-openapi-scheme-generator

# Or in development mode
uv run openapi_generator.py

---

🏗️ Project Structure

CouchDB-OpenAPI-scheme-generator/
├── 📁 couchdb-data/          # CouchDB data (Docker volume)
├── 📁 couchdb-etc/           # CouchDB configuration
├── 📄 docker-compose.yml     # Docker Compose configuration
├── 📄 main.py                # Main application file
├── 📄 openapi_generator.py   # OpenAPI specification generator
├── 📄 pyproject.toml         # Python project configuration
├── 📄 uv.lock                # Dependency lock file
├── 📄 .env                   # Environment variables (create this)
├── 📄 .gitignore             # Git ignore rules
├── 📄 LICENSE                # MIT License
└── 📄 README.md              # This file

---

🛠️ Development

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/SasukeSagara/CouchDB-OpenAPI-scheme-generator.git
   cd couchdb-openapi-scheme-generator
   

2. Install development dependencies:

   uv sync --dev
   

3. Create .env file:

   cp .env.example .env  # If you have an example file
   # Or create manually with:
   # COUCHDB_USER=admin
   # COUCHDB_PASSWORD=your_secure_password
   

4. Start CouchDB:

   docker-compose up -d
   

5. Run tests (if available):

   uv run pytest
   

Code Style

This project follows PEP 8 style guidelines. Consider using:

• black for code formatting
• flake8 or ruff for linting
• mypy for type checking

---

🤝 Contributing

Contributions are welcome! 🎉

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Contribution Guidelines

• 📝 Follow the existing code style
• ✅ Add tests for new features
• 📖 Update documentation as needed
• 🐛 Report bugs using GitHub Issues
• 💡 Suggest enhancements using GitHub Discussions

---

📝 License

This project is distributed under the MIT License. See the LICENSE file for details.

---

⭐ Show Your Support

If you find this project helpful, please consider:

• ⭐ Starring this repository
• 🍴 Forking this repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 📖 Improving documentation
• 🤝 Contributing code

---

Made with ❤️ by SasukeSagara

⭐ Star this repo if you find it useful! ⭐