Swaggler

A CLI tool to convert curl commands and response examples to OpenAPI documentation. Swaggler helps you smuggle your existing API requests into structured, well-documented specs with ease.

Features

• Convert curl commands to OpenAPI/Swagger documentation
• Support for custom operation names and tags
• Ability to append to existing swagger files
• URL template parameter support
• Automatic schema generation from response data
• Support for various content types (JSON, form-data, URL-encoded)
• Automatic parameter extraction from URLs and headers
• Simple and intuitive CLI interface

Installation

npm install -g swaggler
# or
pnpm add -g swaggler
# or
yarn global add swaggler

Usage

swaggler generate -c "curl https://api.example.com/users" -o swagger.yaml

Options

• -c, --curl <curl> - Curl command to convert or path to a file containing curl command
• -i, --input <input> - Path to a file containing curl command
• -o, --output <output> - Output file path (default: swagger.yaml)
• -n, --name <name> - Operation name
• -s, --schema <schema> - URL template with parameters (e.g. /users/{id}/edit)
• -t, --tag <tag> - Tag for the operation
• -p, --output-path <path> - Output file path and directory
• -a, --append <file> - Append to existing swagger file
• -S, --summary <summary> - Custom summary for the operation
• -x, --skip-execution - Skip executing the curl command and use provided response
• -r, --response <response> - JSON response to use when skip-execution is true
• -R, --response-file <file> - Path to a JSON file containing the response to use when skip-execution is true

Examples

# Generate OpenAPI documentation from a curl command
swaggler generate -c "curl -X POST https://api.example.com/users -H 'Content-Type: application/json' -d '{\"name\": \"John Doe\"}'" -o users-api.yaml

# Generate from a file containing curl command
swaggler generate -i curl-commands.txt -o users-api.yaml

# Generate with custom operation name and tags
swaggler generate -c "curl https://api.example.com/users/123" -n "getUser" -t "users" -o users-api.yaml -s /users/{id}

# Generate with custom summary
swaggler generate -c "curl https://api.example.com/users" -S "Retrieve all users" -o users-api.yaml

# Append to existing swagger file
swaggler generate -c "curl https://api.example.com/users" -a existing-swagger.yaml

# Skip curl execution and use provided response directly
swaggler generate -c "curl https://api.example.com/users" -x -r '{"users": [{"id": 1, "name": "John"}]}'

# Skip curl execution and use response from a JSON file
swaggler generate -c "curl https://api.example.com/users" -x -R response.json

# Generate with both curl and response from files
swaggler generate -i curl-command.txt -x -R response.json -o api-spec.yaml

# Generate with form data
swaggler generate -c "curl -X POST https://api.example.com/users -H 'Content-Type: application/x-www-form-urlencoded' -d 'name=John&age=30'" -o users-api.yaml

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build the project
pnpm build

Requirements

• Node.js >= 14.0.0

License

MIT

Author

Farzin Firoozi

Contributing

Contributions are welcome! Feel free to submit a pull request.