🐸 FroggyDocs

Auto-generate API documentation from code annotations. Works with any programming language.

✨ Features

• 📝 Easy Annotations - Add comments to your API code, no config needed
• 🌐 Universal - Works with any language (JavaScript, Python, Go, Ruby, etc.)
• 🎨 Beautiful UI - Interactive API docs with "Try It Out" functionality
• 🔄 Live Reload - Auto-regenerates docs when code changes
• 📦 Multiple Outputs - npm, Docker, GitHub Template
• 🔒 OpenAPI 3.0 - Industry-standard specification

🚀 Quick Start

Via npm (Recommended)

npm install -g froggy-docs
froggy-docs serve

Via Docker

docker run -p 8080:8080 froggy-docs

Via Dart

dart pub global activate froggy_docs
froggy_docs serve

💻 Usage

1. Add Annotations to Your Code

// @api POST /api/users
// @tag Users
// @tag Auth
// @desc Create a new user
// @body name string User's full name
// @body email string User's email
// @auth
app.post('/api/users', async (req, res) => {
  // Your API logic here
});

2. Run the Documentation Server

# Default (localhost:8080)
froggy-docs serve

# Custom port
froggy-docs serve -p 3000

# Network accessible
froggy-docs serve -h 0.0.0.0 -p 8080

# Watch mode (no server)
froggy-docs watch

3. Open in Browser

http://localhost:8080

📖 Annotation Reference

| Annotation | Description | Example | |------------|-------------|---------| | @api | Define endpoint | @api GET /users | | @desc | Description | @desc Get all users | | @tag | Category | @tag Users | | @body | Request body field | @body name string User's name | | @body-json | Inline JSON schema | @body-json {...} | | @body-file | From JSON file | @body-file ./schema.json | | @auth | Requires auth | @auth |

Full guide: docs/annotations.md

🐳 Docker

Build

docker build -t froggy-docs .

Run

# Default
docker run -p 8080:8080 froggy-docs

# Custom port
docker run -p 3000:8080 froggy-docs serve -p 3000

# Mount project
docker run -v $(pwd):/app -p 8080:8080 froggy-docs

Docker Compose

version: '3'
services:
  froggy-docs:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - .:/app
    command: serve -h 0.0.0.0

⚙️ Configuration

Create .froggyrc in your project root:

{
  "server": {
    "port": 8080,
    "host": "localhost"
  },
  "paths": {
    "include": ["lib/", "src/", "api/"],
    "exclude": ["test/", "node_modules/"]
  },
  "output": {
    "format": "openapi",
    "file": "docs/froggy_docs.json"
  }
}

See: .froggyrc.example

🌐 Supported Languages

| Language | Extensions | Comment | |----------|------------|----------| | JavaScript/TypeScript | .js, .ts, .jsx, .tsx | // | | Python | .py | # | | Ruby | .rb | # | | Go | .go | // | | Rust | .rs | // | | Dart | .dart | // | | Java/Kotlin | .java, .kt | // | | PHP | .php | // | | C# | .cs | // | | C/C++ | .c, .cpp, .h | // |

📦 Installation Options

npm

npm install -g froggy-docs

pip

pip install froggy-docs

Docker

docker run -p 8080:8080 froggy-docs

Standalone Binary

Download from Releases

🤝 Contributing

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

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Shelf - HTTP server
• Watcher - File watching
• Jaspr - Web framework