{"_id":"@ansrivas/openapi-snippets","name":"@ansrivas/openapi-snippets","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ansrivas/openapi-snippets","version":"1.0.0","description":"OpenAPI to multi-language code snippet generator","type":"module","main":"dist/index.js","bin":{"openapi-snippets":"dist/cli.js"},"scripts":{"build":"tsc","prepare":"tsc","prepublishOnly":"tsc","start":"node dist/cli.js","dev":"tsc && node dist/cli.js","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","lint":"eslint src --ext .ts","lint:fix":"eslint src --ext .ts --fix","format":"prettier --write \"src/**/*.ts\"","clean":"rm -rf dist"},"keywords":["openapi","snippets","httpsnippet","code-generation"],"license":"MIT","dependencies":{"@readme/httpsnippet":"^11.1.0","@readme/oas-to-har":"^30.0.3","@readme/oas-to-snippet":"^29.3.8","commander":"^12.0.0","js-yaml":"^4.1.1","oas":"^31.1.2","oas-normalize":"^16.0.2"},"devDependencies":{"@eslint/js":"^10.0.1","@types/js-yaml":"^4.0.9","@types/node":"^22.0.0","eslint":"^10.1.0","prettier":"^3.8.1","typescript":"^5.3.3","typescript-eslint":"^8.57.1","vitest":"^3.2.4"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"gitHead":"a4967da8fc998c64f5fca1aa39ee4613a4778356","types":"./dist/index.d.ts","_id":"@ansrivas/openapi-snippets@1.0.0","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-SoCHmiRKkH4e9KOQjLDvIcmGAsYAfiGOIdjGoAfBI7vL6cY5uymGLVDYa/d68TknYG4KsWQu+NAwzrb1+imx9Q==","shasum":"6fdeb428d69b202f54a254990f864efc0d891aae","tarball":"https://registry.npmjs.org/@ansrivas/openapi-snippets/-/openapi-snippets-1.0.0.tgz","fileCount":14,"unpackedSize":79742,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB0e5VxdKlZgPItJWq1H5z7bsbfInshrChhsMF75IVocAiEAnZIJUKqZtYR5p9cEn6umUyx7dpgIO7DHgV9FYrsd6dk="}]},"_npmUser":{"name":"ansrivas","email":"best.ankur@gmail.com"},"directories":{},"maintainers":[{"name":"ansrivas","email":"best.ankur@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openapi-snippets_1.0.0_1774278373365_0.37804327391881487"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-23T15:06:13.264Z","1.0.0":"2026-03-23T15:06:13.519Z","modified":"2026-03-23T15:06:13.729Z"},"maintainers":[{"name":"ansrivas","email":"best.ankur@gmail.com"}],"description":"OpenAPI to multi-language code snippet generator","keywords":["openapi","snippets","httpsnippet","code-generation"],"license":"MIT","readme":"# OpenAPI Snippets Generator\n\nCLI tool that takes an OpenAPI spec and injects `x-codeSamples` per endpoint for documentation renderers like Redoc and Swagger UI.\n\n## Installation\n\n### Global install\n\n```bash\nnpm install -g .\n# or publish to a registry and:\n# npm install -g openapi-snippets\n```\n\nThen run directly:\n\n```bash\nopenapi-snippets -i spec.yaml -l 'shell:curl,node:axios,python:requests'\n```\n\n### Local (project-level)\n\n```bash\nnpm install\nnpm run build\nnode dist/cli.js -i combined_output.yaml -l 'shell:curl,node:axios,python:requests'\nredocly build-docs combined_output_updated.yaml --output combined_output.html\n```\n\n## Quick Start\n\n```bash\n# Inject x-codeSamples into a copy of the spec (combined_output_updated.yaml)\nopenapi-snippets -i combined_output.yaml -l 'shell:curl,node:axios,python:requests'\n\n# Target specific operations\nopenapi-snippets -i combined_output.yaml -l 'shell:curl,node:axios' \\\n  --operation-ids 'query_users,create_user'\n```\n\n## What It Does\n\n1. Parses an OpenAPI 3.x spec (YAML or JSON)\n2. Generates code snippets for every endpoint using the selected languages/clients\n3. Writes a new `<filename>_updated.<ext>` file with `x-codeSamples` injected per operation\n4. Renderers like Redoc display a language selector with runnable examples for each endpoint\n\n## CLI Reference\n\n```\nRequired:\n  -i, --input <path>          OpenAPI file path\n  -l, --languages <list>      Comma-separated language:client pairs\n\nOptions:\n  --operation-ids <ids>       Comma-separated operation IDs to include\n  --include-tags <tags>       Comma-separated tags to include\n  --exclude-tags <tags>       Comma-separated tags to exclude\n  --path-regex <regex>        Regex to filter paths\n  --methods <methods>         Comma-separated HTTP methods (GET,POST,PUT,DELETE)\n  --auth-file <path>          JSON file with auth config\n  --server-index <index>      Server index from spec (default: 0)\n  --server-vars <vars>        Server variable overrides (key=value,key2=value2)\n  --include-optional          Include optional parameters in snippets\n```\n\n## Supported Languages\n\n| Language | Clients                                 |\n| -------- | --------------------------------------- |\n| `shell`  | `curl`                                  |\n| `node`   | `axios`, `native`, `unirest`, `request` |\n| `python` | `requests`, `python3`                   |\n| `java`   | `okhttp`, `unirest`, `httpcomponents`   |\n| `go`     | `native`                                |\n| `csharp` | `httpclient`, `restsharp`               |\n| `ruby`   | `native`, `net-http`                    |\n| `php`    | `curl`, `guzzle`                        |\n| `swift`  | `nsurlsession`, `urlsession`            |\n| `kotlin` | `okhttp`                                |\n\n## Usage Examples\n\n### Inject code samples into spec\n\n```bash\n# All operations, 5 languages\nopenapi-snippets -i combined_output.yaml \\\n  -l 'shell:curl,node:axios,python:requests,go,java:okhttp'\n# Outputs: combined_output_updated.yaml\n```\n\n### Filter by tags or methods\n\n```bash\nopenapi-snippets -i combined_output.yaml \\\n  -l 'shell:curl,node:axios' \\\n  --include-tags 'querytimescale_fixed_search' \\\n  --methods GET,POST\n```\n\n### Authentication\n\nCreate `auth.json`:\n\n```json\n{\n  \"bearerToken\": \"your-token-here\"\n}\n```\n\n```bash\nopenapi-snippets -i openapi.yaml -l 'shell:curl' --auth-file auth.json\n```\n\n## Output\n\nWrites `<input>_updated.<ext>` in the same directory as the input file. The original file is never modified.\n\n### x-codeSamples format\n\nThe injected `x-codeSamples` use the Redoc extension format:\n\n```yaml\npaths:\n  /api/v1/users:\n    get:\n      x-codeSamples:\n        - lang: Shell (curl)\n          label: shell-curl\n          source: |\n            curl --request GET \\\n                 --url https://example.com/api/v1/users \\\n                 --header 'accept: application/json'\n        - lang: Node.js (axios)\n          label: node-axios\n          source: |\n            import axios from 'axios';\n            ...\n```\n\n## Exit Codes\n\n| Code | Meaning                                  |\n| ---- | ---------------------------------------- |\n| 0    | All snippets generated successfully      |\n| 1    | Failure (parse error, invalid spec, etc) |\n\n## Programmatic Usage\n\n```typescript\nimport { generate } from './dist/index.js';\n\nawait generate({\n  input: './openapi.yaml',\n  languages: [\n    { language: 'shell', client: 'curl' },\n    { language: 'node', client: 'axios' },\n  ],\n  filters: { includeTags: ['public'] },\n  auth: {},\n  server: { index: 0, variables: {} },\n  includeOptional: false,\n});\n// Writes ./openapi_updated.yaml with x-codeSamples\n```\n\n## Technical Details\n\n- **Snippet generation**: `@readme/oas-to-snippet` (primary) with `@readme/oas-to-har` + `@readme/httpsnippet` fallback\n- **Spec parsing**: `oas-normalize` + `oas`\n- **YAML handling**: `js-yaml`\n- **Language target format**: oasToSnippet expects `[language, client]` arrays, not `\"lang:client\"` strings\n- **Spec output format**: `_updated` files preserve the original format (YAML stays YAML, JSON stays JSON)\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-a267f34dd0c10579d8023bafcfded21b"}