{"id":15952200,"url":"https://github.com/idsulik/swama","last_synced_at":"2025-05-08T20:52:58.653Z","repository":{"id":257220330,"uuid":"857654794","full_name":"idsulik/swama","owner":"idsulik","description":"Swama is a powerful command-line interface (CLI) tool for interacting with Swagger/OpenAPI definitions","archived":false,"fork":false,"pushed_at":"2024-11-03T07:26:26.000Z","size":103,"stargazers_count":71,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T18:06:51.738Z","etag":null,"topics":["go","golang","openai","rest-api","restful","swagger"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/idsulik/swama","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/idsulik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-15T08:42:14.000Z","updated_at":"2025-03-26T04:57:51.000Z","dependencies_parsed_at":"2024-10-27T15:16:18.176Z","dependency_job_id":"ad070e1f-3280-4fa1-a0c6-f9d312d84d96","html_url":"https://github.com/idsulik/swama","commit_stats":{"total_commits":44,"total_committers":1,"mean_commits":44.0,"dds":0.0,"last_synced_commit":"516b1875c25518d9a33c95fe299e13cd5a2c38d6"},"previous_names":["idsulik/swama"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idsulik%2Fswama","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idsulik%2Fswama/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idsulik%2Fswama/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idsulik%2Fswama/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/idsulik","download_url":"https://codeload.github.com/idsulik/swama/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253149366,"owners_count":21861717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","openai","rest-api","restful","swagger"],"created_at":"2024-10-07T13:07:12.816Z","updated_at":"2025-05-08T20:52:58.634Z","avatar_url":"https://github.com/idsulik.png","language":"Go","readme":"# Swama \n[![Go Report Card](https://goreportcard.com/badge/github.com/idsulik/swama)](https://goreportcard.com/report/github.com/idsulik/swama)\n[![Version](https://img.shields.io/github/v/release/idsulik/swama)](https://github.com/idsulik/swama/v2/releases)\n[![License](https://img.shields.io/github/license/idsulik/swama)](https://github.com/idsulik/swama/v2/blob/main/LICENSE)\n[![GoDoc](https://pkg.go.dev/badge/github.com/idsulik/swama)](https://pkg.go.dev/github.com/idsulik/swama)\n\nSwama is a powerful command-line interface (CLI) tool for interacting with Swagger/OpenAPI definitions. It allows you to list, view, convert, and explore API specifications directly from the command line. Swama supports JSON and YAML formats for Swagger files, and it's available for multiple platforms through pre-built binaries.\n\n## Features\n\n- **List and View Endpoints**: Explore API endpoints and their details.\n- **Convert Endpoints**: Convert API endpoints to `curl` or `fetch` commands for testing.\n- **Explore Tags and Servers**: Easily view API tags and servers.\n- **Flexible Filtering**: Filter endpoints by method, tag, or specific endpoint using wildcards.\n- **Grouping**: Group endpoint listings by tag or method.\n- **Support for Autocompletion**: Enable shell autocompletion for faster workflows.\n- **Mock Server**: Start a local mock server based on your Swagger/OpenAPI definitions. The mock server simulates API responses based on the specification, enabling rapid prototyping and testing.\n\n## Installation\n\n### Download Pre-Built Binaries\n\nSwama provides pre-built binaries for Linux, macOS, and Windows. You can download the appropriate binary from the [releases page](https://github.com/idsulik/swama/v2/releases).\n\n1. **Download the latest release**:\n    - Navigate to the [releases page](https://github.com/idsulik/swama/v2/releases).\n    - Choose the binary for your platform (Linux, macOS, Windows).\n\n2. **Install the binary**:\n    - **Linux/MacOS**: Move the binary to a directory in your `$PATH`:\n      ```bash\n      sudo mv swama /usr/local/bin/\n      sudo chmod +x /usr/local/bin/swama\n      ```\n    - **Windows**: Add the binary to your system's `PATH` for global access.\n\n### Build from Source\n\nAlternatively, you can build Swama from source:\n\n```bash\ngit clone https://github.com/idsulik/swama\ncd swama\ngo build -o swama\n```\n\n## Usage\n\nAfter installation, you can use the `swama` command to interact with Swagger/OpenAPI files.\n\n### General Command Usage\n\n```bash\nswama [command]\n```\n\n### Available Commands\n\n- **`completion`**: Generate the autocompletion script for the specified shell.\n- **`endpoints`**: Interact with API endpoints (list, view, convert).\n- **`mock-server`**: Start a local mock server based on the Swagger file.\n- **`components`**: Interact with API components (list, view).\n- **`info`**: Display general information about the Swagger file.\n- **`servers`**: List API servers.\n- **`tags`**: List and view API tags.\n\n### Global Flags\n\n- **`-f, --file string`**: Path to the Swagger JSON/YAML file. If not provided, the tool will attempt to locate the Swagger file in the current directory.\n- **`-h, --help`**: Displays help for the `swama` command or any subcommand.\n\n---\n\n## Commands Overview\n\n### Endpoints\n\nThe `endpoints` command allows you to list, view, and convert API endpoints.\n\n#### List Endpoints\n\nLists all API endpoints from a Swagger/OpenAPI file.\n\n```bash\nswama endpoints list [flags]\n```\n\n**Available Flags**:\n\n- `-e, --endpoint string`: Filter by endpoint, supports wildcard.\n- `-g, --group string`: Group output by tag or method (default: \"tag\").\n- `-m, --method string`: Filter by method (GET, POST, etc.).\n- `-t, --tag string`: Filter by tag.\n\n**Example**:\n\n```bash\nswama endpoints list\n```\n\n![preview](https://github.com/user-attachments/assets/59937e51-3992-4ee7-b629-a9d004310afc)\n\n#### View Endpoint Details\n\nDisplays detailed information for a specific API endpoint.\n\n```bash\nswama endpoints view [flags]\n```\n\n**Available Flags**:\n\n- `-e, --endpoint string`: Specify the endpoint to view.\n- `-m, --method string`: Specify the method (GET, POST, etc.) of the endpoint to view.\n\n**Example**:\n\n```bash\nswama endpoints view --method=GET --endpoint=/user\n```\n\n![preview](https://github.com/user-attachments/assets/7eff7784-f276-4027-9606-f59fdd6b0951)\n\n\n#### Convert an Endpoint\n\nConverts an API endpoint to either a `curl` or `fetch` command.\n\n```bash\nswama endpoints convert [flags]\n```\n\n**Available Flags**:\n\n- `-e, --endpoint string`: Specify the endpoint to convert.\n- `-m, --method string`: Specify the method (GET, POST, etc.).\n- `-t, --type string`: Type to convert to (`curl`, `fetch`).\n\n**Example**:\n\n```bash\nswama endpoints convert --file swagger.yaml --endpoint /api/users --method POST --type curl\n```\n\n### Mock Server\n\nThe `mock-server` command allows you to run a local mock server based on a Swagger/OpenAPI specification file. This mock server simulates API responses, making it easier to test and prototype API interactions locally.\n\n#### Run Mock Server\n\nStarts a mock server.\n\n```bash\nswama mock-server run [flags]\n```\n**Available Flags**:\n\n- `--port int`: Specify the port for the mock server (default: 8080).\n- `--host string`: Set the host address for the mock server (default: \"localhost\").\n- `--delay int`: Add a delay in milliseconds to each response, useful for simulating network latency.\n- `--default-response-code int`: Set the default response code to use (default: 200).\n- `--default-response-type string`: Set the default response type to use (default: \"json\").\n\n**Example**:\n\n```bash\nswama mock-server run --port 8081 --host 0.0.0.0 --delay 200\n```\n\nThis command starts a mock server on port 8081, accessible on all network interfaces (`0.0.0.0`), with a 200ms delay added to each response to simulate latency.\n\n### Components\n\nThe `components` command allows you to list, and view API components(requests, responses etc.).\n\n#### List Components\n\nLists all API components from a Swagger/OpenAPI file.\n\n```bash\nswama components list [flags]\n```\n\n**Example**:\n\n```bash\nswama components list\n```\n\n![preview](https://github.com/user-attachments/assets/a83c32ba-7b8d-4aec-b9c0-33e0bacfdff8)\n\n#### View Component Details\n\nDisplays detailed information for a specific API component.\n\n```bash\nswama components view [flags]\n```\n\n**Available Flags**:\n\n- `-n, --name string`: Specify the component's name to view.\n\n**Example**:\n\n```bash\nswama components view --name customer\n```\n\n![preview](https://github.com/user-attachments/assets/073d93bd-d348-48e2-b750-571e803c0a73)\n\n### Tags\n\nThe `tags` command allows you to list API tags in the Swagger/OpenAPI file.\n\n```bash\nswama tags list [flags]\n```\n\n**Available Flags**:\n\n- `-h, --help`: Displays help for the `tags` command.\n\n**Example**:\n\n```bash\nswama tags list --file swagger.yaml\n```\n\n### Servers\n\nThe `servers` command allows you to list servers from the Swagger/OpenAPI file.\n\n```bash\nswama servers list [flags]\n```\n\n**Available Flags**:\n\n- `-h, --help`: Displays help for the `servers` command.\n\n**Example**:\n\n```bash\nswama servers list --file swagger.yaml\n```\n\n### Info\n\nDisplays general information about the Swagger/OpenAPI file, such as the version, title, and description.\n\n```bash\nswama info view --file swagger.yaml\n```\n\n![preview](https://github.com/user-attachments/assets/6fd03077-e7f6-4baa-8b17-17626c5d12a2)\n---\n\n## Autocompletion\n\nSwama supports autocompletion for various shells, such as Bash and Zsh. You can generate a script for your shell to enable autocompletion.\n\n### Example: Generate Bash Completion Script\n\n```bash\nswama completion bash \u003e /etc/bash_completion.d/swama\n```\n\n### Example: Generate Zsh Completion Script\n\n```bash\nswama completion zsh \u003e ~/.zsh/completion/_swama\n```\n\n## Contributing\n\nContributions to Swama are welcome! Feel free to submit issues or pull requests on the [GitHub repository](https://github.com/idsulik/swama).\n\n## License\n\nSwama is licensed under the MIT License. See the `LICENSE` file for more details.\n\n---\n\nWith Swama, interacting with Swagger/OpenAPI files is straightforward and efficient. Whether you're exploring API endpoints, converting them to testable commands, or managing servers and tags, Swama provides a simple and powerful interface for your needs. Get started by downloading the binary or building from source today!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidsulik%2Fswama","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidsulik%2Fswama","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidsulik%2Fswama/lists"}