{"id":42697424,"url":"https://github.com/LukasParke/prettier-plugin-openapi","last_synced_at":"2026-02-09T02:01:34.108Z","repository":{"id":316509869,"uuid":"1063687697","full_name":"LukasParke/prettier-plugin-openapi","owner":"LukasParke","description":"A prettier plugin to organize OpenAPI files for human readability","archived":false,"fork":false,"pushed_at":"2025-11-10T18:25:01.000Z","size":353,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-22T02:52:52.607Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LukasParke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T01:36:01.000Z","updated_at":"2025-11-10T18:25:04.000Z","dependencies_parsed_at":"2025-10-30T04:13:48.834Z","dependency_job_id":"978887ae-75a4-44ef-93f6-b9cf6adc30d7","html_url":"https://github.com/LukasParke/prettier-plugin-openapi","commit_stats":null,"previous_names":["lukehagar/prettier-plugin-openapi","lukasparke/prettier-plugin-openapi"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/LukasParke/prettier-plugin-openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Fprettier-plugin-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Fprettier-plugin-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Fprettier-plugin-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Fprettier-plugin-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LukasParke","download_url":"https://codeload.github.com/LukasParke/prettier-plugin-openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Fprettier-plugin-openapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29254302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T01:52:29.835Z","status":"online","status_checked_at":"2026-02-09T02:00:09.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-01-29T14:00:32.941Z","updated_at":"2026-02-09T02:01:34.099Z","avatar_url":"https://github.com/LukasParke.png","language":"TypeScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# Prettier Plugin OpenAPI\n\nA Prettier plugin for formatting OpenAPI/Swagger JSON and YAML files with intelligent key sorting, proper indentation, and support for modular OpenAPI file structures.\n\n## Features\n\n- 🎯 **OpenAPI/Swagger Support**: Formats both JSON and YAML OpenAPI specifications\n- 🔄 **Smart Key Sorting**: Automatically sorts OpenAPI keys in the recommended order\n- 📁 **Modular File Support**: Handles both monolithic and modular OpenAPI file structures\n- 🧩 **Component Files**: Supports individual component files (schemas, parameters, responses, etc.)\n- 📝 **YAML \u0026 JSON**: Supports both `.yaml/.yml` and `.json` file formats\n- 🎨 **Consistent Formatting**: Applies consistent indentation and line breaks\n- 🔌 **Vendor Extensions**: Programmatic loading of vendor-specific extensions\n- ⚡ **Fast**: Built with performance in mind using modern JavaScript\n- 🧪 **Comprehensive Testing**: 142 tests with 95.69% line coverage\n- 🚀 **CI/CD Ready**: Automated testing, building, and publishing\n- 🔒 **Strict Validation**: Properly rejects non-OpenAPI content\n- 📊 **High Quality**: Biome, Prettier, and TypeScript for code quality\n\n## Current Status\n\n✅ **Production Ready**: Version 1.0.1 with comprehensive test coverage  \n✅ **Modern Tooling**: Updated to use Biome for fast linting and formatting  \n✅ **Comprehensive Testing**: 142 tests covering all major functionality  \n✅ **High Performance**: Optimized for large OpenAPI files  \n✅ **Active Development**: Regular updates and improvements\n\n## Installation\n\n```bash\nnpm install --save-dev prettier-plugin-openapi\n# or\npnpm add --dev prettier-plugin-openapi\n# or\nyarn add --dev prettier-plugin-openapi\n# or\nbun add --dev prettier-plugin-openapi\n```\n\n## Usage\n\n### Command Line\n\n```bash\n# Format a single file\npnpx prettier --write api.yaml\n\n# Format all OpenAPI files in a directory\npnpx prettier --write \"**/*.{openapi.json,openapi.yaml,swagger.json,swagger.yaml}\"\n\n# Format with specific options\npnpx prettier --write api.yaml --tab-width 4 --print-width 100\n```\n\n### Configuration\n\nAdd the plugin to your Prettier configuration:\n\n**package.json**\n```json\n{\n  \"prettier\": {\n    \"plugins\": [\"prettier-plugin-openapi\"]\n  }\n}\n```\n\n**.prettierrc**\n```json\n{\n  \"plugins\": [\"prettier-plugin-openapi\"],\n  \"tabWidth\": 2,\n  \"printWidth\": 80\n}\n```\n\n**.prettierrc.js**\n```javascript\nmodule.exports = {\n  plugins: ['prettier-plugin-openapi'],\n  tabWidth: 2,\n  printWidth: 80,\n};\n```\n\n## Supported File Extensions\n\n- `.openapi.json`\n- `.openapi.yaml`\n- `.openapi.yml`\n- `.swagger.json`\n- `.swagger.yaml`\n- `.swagger.yml`\n- `.json` (for component files)\n- `.yaml` / `.yml` (for component files)\n\n## Modular File Structure Support\n\nThe plugin supports both monolithic and modular OpenAPI file structures:\n\n### Monolithic Structure\n```\napi.yaml                    # Single file with everything\n```\n\n### Modular Structure\n```\n├─ openapi.yaml             # Root document\n├─ paths/                    # Path files\n│  ├─ users.yaml\n│  ├─ users_{id}.yaml\n│  └─ auth_login.yaml\n├─ components/               # Component files\n│  ├─ schemas/\n│  │  ├─ User.yaml\n│  │  ├─ UserCreate.yaml\n│  │  └─ Error.yaml\n│  ├─ parameters/\n│  │  ├─ CommonPagination.yaml\n│  │  └─ UserId.yaml\n│  ├─ responses/\n│  │  ├─ ErrorResponse.yaml\n│  │  └─ UserResponse.yaml\n│  ├─ requestBodies/\n│  │  └─ UserCreateBody.yaml\n│  ├─ headers/\n│  │  └─ RateLimitHeaders.yaml\n│  ├─ examples/\n│  │  └─ UserExample.yaml\n│  ├─ securitySchemes/\n│  │  └─ BearerAuth.yaml\n│  ├─ links/\n│  │  └─ UserCreatedLink.yaml\n│  └─ callbacks/\n│     └─ NewMessageCallback.yaml\n└─ webhooks/                 # Webhook files\n   └─ messageCreated.yaml\n```\n\n## Key Sorting\n\nThe plugin automatically sorts OpenAPI keys in the recommended order:\n\n\u003e 📖 **Complete Key Reference**: For a comprehensive reference of all keys, their ordering, and detailed reasoning, see [KEYS.md](./KEYS.md).\n\n## Examples\n\n### Monolithic File Structure\n\n#### Before (unformatted):\n```yaml\npaths:\n  /users:\n    get:\n      responses:\n        '200':\n          description: OK\ncomponents:\n  schemas:\n    User:\n      type: object\nopenapi: 3.0.0\ninfo:\n  version: 1.0.0\n  title: My API\n```\n\n#### After (formatted):\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: My API\n  version: 1.0.0\npaths:\n  /users:\n    get:\n      responses:\n        '200':\n          description: OK\ncomponents:\n  schemas:\n    User:\n      type: object\n```\n\n### Modular File Structure\n\n#### Root Document (`openapi.yaml`):\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: My API\n  version: 1.0.0\npaths:\n  $ref: './paths/users.yaml'\ncomponents:\n  schemas:\n    $ref: './components/schemas/User.yaml'\n```\n\n#### Component File (`components/schemas/User.yaml`):\n```yaml\ntype: object\nproperties:\n  id:\n    type: integer\n  name:\n    type: string\nrequired:\n  - id\n  - name\n```\n\n#### Path File (`paths/users.yaml`):\n```yaml\nget:\n  summary: Get users\n  responses:\n    '200':\n      description: Success\n      content:\n        application/json:\n          schema:\n            type: array\n            items:\n              $ref: '../components/schemas/User.yaml'\n```\n\n## Vendor Extension Guide\n\n### Adding Your Vendor Extensions\n\nThe plugin supports a simple system for vendors to contribute custom extensions. \n\nHere's how to add your vendor extensions:\n\n#### Step 1: Create Your Vendor Extension File\n\nCreate a new TypeScript file in `src/extensions/vendor/your-vendor.ts`:\n\n```typescript\n/**\n * Your Vendor Extensions\n * \n * Your vendor extensions for OpenAPI formatting.\n * Website: https://your-vendor.com\n */\n\nimport { defineConfig } from \"../index.js\";\n\nexport const yourVendor = defineConfig({\n  info: {\n    name: 'Your Vendor',\n    website: 'https://your-vendor.com',\n    support: 'support@your-vendor.com'\n  },\n  extensions: {\n    // Define your extensions here\n  }\n});\n```\n\n#### Step 2: Register Your Vendor\n\nAdd your vendor to the vendor loader in `src/extensions/vendor-loader.ts`:\n\n```typescript\n// Import your vendor extension\nimport { yourVendor } from './vendor/your-vendor.js';\n\n// Add to the vendorModules array\nconst vendorModules = [\n  speakeasy, \n  postman, \n  redoc,\n  yourVendor  // Add your vendor here\n];\n```\n\n#### Step 3: Define Your Extensions\n\nUse the `before()` and `after()` helper functions to position your extensions relative to standard OpenAPI keys. The system now provides **full IntelliSense support** with type-safe key suggestions:\n\n```typescript\nextensions: {\n  'top-level': (before, after) =\u003e {\n    // ✅ IntelliSense shows: 'swagger', 'openapi', 'info', 'paths', etc.\n    return {\n      'x-your-vendor-sdk': before('info'),        // ✅ Type-safe: 'info' is valid\n      'x-your-vendor-auth': after('paths'),       // ✅ Type-safe: 'paths' is valid\n      // 'x-invalid': before('invalidKey'),       // ❌ TypeScript error: 'invalidKey' not valid\n    };\n  },\n  'operation': (before, after) =\u003e {\n    // ✅ IntelliSense shows: 'summary', 'operationId', 'parameters', 'responses', etc.\n    return {\n      'x-your-vendor-retries': after('parameters'), // ✅ Type-safe: 'parameters' is valid\n      'x-your-vendor-timeout': before('responses'), // ✅ Type-safe: 'responses' is valid\n    };\n  },\n  'schema': (before, after) =\u003e {\n    // ✅ IntelliSense shows: '$ref', 'title', 'type', 'format', 'example', etc.\n    return {\n      'x-your-vendor-validation': after('type'),   // ✅ Type-safe: 'type' is valid\n      'x-your-vendor-example': after('example'),    // ✅ Type-safe: 'example' is valid\n    };\n  }\n}\n```\n\n### 🎯 Enhanced IntelliSense Features\n\nThe vendor extension system now provides comprehensive IntelliSense support:\n\n#### Type-Safe Key Suggestions\n- **Context-aware autocomplete**: Each context shows only valid OpenAPI keys\n- **Real-time validation**: TypeScript errors for invalid keys\n- **Hover documentation**: Detailed information about each key's purpose\n\n#### Available Contexts with IntelliSense\n- `'top-level'` → Shows: `swagger`, `openapi`, `info`, `paths`, `components`, etc.\n- `'info'` → Shows: `title`, `version`, `description`, `contact`, `license`, etc.\n- `'operation'` → Shows: `summary`, `operationId`, `parameters`, `responses`, etc.\n- `'schema'` → Shows: `$ref`, `title`, `type`, `format`, `example`, etc.\n- `'parameter'` → Shows: `name`, `description`, `in`, `required`, `schema`, etc.\n- `'response'` → Shows: `description`, `headers`, `content`, `links`\n- `'securityScheme'` → Shows: `type`, `description`, `name`, `in`, `scheme`, etc.\n- `'server'` → Shows: `url`, `description`, `variables`\n- `'tag'` → Shows: `name`, `description`, `externalDocs`\n- `'externalDocs'` → Shows: `description`, `url`\n- `'webhook'` → Shows: `summary`, `operationId`, `parameters`, `responses`, etc.\n- `'definitions'` → Shows schema keys (Swagger 2.0)\n- `'securityDefinitions'` → Shows security scheme keys (Swagger 2.0)\n\n#### Enhanced Helper Functions\n\n```typescript\nimport { createPositionHelpers } from \"../index.js\";\n\n// Get enhanced helpers for a specific context\nconst helpers = createPositionHelpers('operation');\n\n// Type-safe positioning\nhelpers.before('parameters');  // ✅ IntelliSense shows valid operation keys\nhelpers.after('responses');    // ✅ IntelliSense shows valid operation keys\n\n// Additional utilities\nconst availableKeys = helpers.getAvailableKeys();  // Get all valid keys\nconst isValid = helpers.isValidKey('summary');      // Check if key is valid\n```\n\n### Supported Contexts\n\nYou can define extensions for these OpenAPI contexts:\n\n- `'top-level'` - Root OpenAPI document\n- `'info'` - API information section\n- `'operation'` - HTTP operations (GET, POST, etc.)\n- `'parameter'` - Operation parameters\n- `'schema'` - Data schemas\n- `'response'` - Operation responses\n- `'securityScheme'` - Security schemes\n- `'server'` - Server definitions\n- `'tag'` - API tags\n- `'externalDocs'` - External documentation\n- `'webhook'` - Webhook definitions\n- `'definitions'` - Swagger 2.0 definitions\n- `'securityDefinitions'` - Swagger 2.0 security definitions\n\n### Standard OpenAPI Keys Reference\n\nWhen positioning your extensions, you can reference these standard OpenAPI keys:\n\n#### Top-Level Keys\n- `openapi`, `swagger`, `info`, `externalDocs`, `servers`, `security`, `tags`, `paths`, `webhooks`, `components`\n\n#### Info Section Keys\n- `title`, `version`, `summary`, `description`, `termsOfService`, `contact`, `license`\n\n#### Operation Keys\n- `summary`, `operationId`, `description`, `externalDocs`, `tags`, `deprecated`, `security`, `servers`, `parameters`, `requestBody`, `responses`, `callbacks`\n\n#### Schema Keys\n- `$ref`, `title`, `description`, `type`, `format`, `enum`, `default`, `example`, `properties`, `required`, `items`, `allOf`, `anyOf`, `oneOf`, `not`\n\n#### Parameter Keys\n- `name`, `description`, `in`, `required`, `deprecated`, `schema`, `content`, `style`, `explode`, `allowReserved`, `example`\n\n#### Response Keys\n- `description`, `headers`, `content`, `links`\n\n#### Security Scheme Keys\n- `type`, `description`, `name`, `in`, `scheme`, `bearerFormat`, `flows`, `openIdConnectUrl`\n\n#### Server Keys\n- `url`, `description`, `variables`\n\n#### Tag Keys\n- `name`, `description`, `externalDocs`\n\n#### External Docs Keys\n- `description`, `url`\n\n#### Webhook Keys\n- `summary`, `operationId`, `description`, `deprecated`, `tags`, `security`, `servers`, `parameters`, `requestBody`, `responses`, `callbacks`\n\n\u003e 📖 **Complete Key Reference**: For a comprehensive reference of all keys, their ordering, and detailed reasoning, see [KEYS.md](./KEYS.md).\n\n### Positioning Your Extensions\n\nUse the helper functions to position your extensions:\n\n- `before(key)` - Position before a standard OpenAPI key\n- `after(key)` - Position after a standard OpenAPI key\n\n#### Example: Positioning Extensions\n\n```typescript\n'operation': (before, after) =\u003e {\n  return {\n    // Position before standard keys\n    'x-your-vendor-auth': before('security'),\n    'x-your-vendor-rate-limit': before('parameters'),\n    \n    // Position after standard keys  \n    'x-your-vendor-retries': after('parameters'),\n    'x-your-vendor-timeout': after('responses'),\n    \n    // Position relative to other extensions\n    'x-your-vendor-cache': after('x-your-vendor-retries'),\n  };\n}\n```\n\n### Extension Naming Convention\n\nFollow these naming conventions for your extensions:\n\n- Use your vendor prefix: `x-your-vendor-`\n- Use descriptive names: `x-your-vendor-retries`, `x-your-vendor-timeout`\n- Keep names consistent across contexts\n- Use kebab-case for multi-word extensions\n\n### Testing Your Extensions\n\n1. **Build the project**: `bun run build`\n2. **Run tests**: `bun test`\n3. **Test with real OpenAPI files**: Create test files with your extensions\n4. **Verify positioning**: Check that your extensions appear in the correct order\n\n### Extension Collision Detection\n\nThe system automatically detects and warns about extension key collisions:\n\n```\n⚠️  Extension collision detected!\n   Key: \"x-common-extension\" in context \"operation\"\n   Already defined by: Vendor A\n   Conflicting with: Vendor B\n   Using position from: Vendor A (5)\n   Ignoring position from: Vendor B (3)\n```\n\n### Advanced Type Safety\n\nThe vendor extension system provides comprehensive TypeScript support:\n\n#### Type Definitions\n```typescript\nimport { \n  type VendorExtensions, \n  type ContextExtensionFunction,\n  type OpenAPIContext,\n  type ExtensionKey \n} from \"../index.js\";\n\n// Type-safe extension configuration\nconst extensions: VendorExtensions = {\n  'top-level': (before, after) =\u003e {\n    // before and after are type-safe for top-level keys\n    return {\n      'x-my-extension': before('info'),\n      'x-my-config': after('paths')\n    };\n  }\n};\n```\n\n#### Extension Key Validation\n```typescript\nimport { isValidExtensionKey } from \"../index.js\";\n\n// Validate extension keys follow OpenAPI conventions\nconst isValid = isValidExtensionKey('x-my-vendor-extension'); // ✅ true\nconst isInvalid = isValidExtensionKey('my-extension');       // ❌ false\n```\n\n#### Context-Specific Helpers\n```typescript\nimport { createPositionHelpers } from \"../index.js\";\n\n// Get type-safe helpers for a specific context\nconst operationHelpers = createPositionHelpers('operation');\n\n// All functions are type-safe\noperationHelpers.before('summary');     // ✅ Valid operation key\noperationHelpers.after('responses');   // ✅ Valid operation key\noperationHelpers.isValidKey('summary'); // ✅ true\noperationHelpers.getAvailableKeys();    // Returns all valid operation keys\n```\n\n### Best Practices\n\n1. **Use descriptive extension names** that clearly indicate their purpose\n2. **Position extensions logically** relative to related standard keys\n3. **Document your extensions** in your vendor documentation\n4. **Test thoroughly** with real OpenAPI files\n5. **Follow OpenAPI extension conventions** (x-vendor-name format)\n6. **Consider extension conflicts** when choosing names\n7. **Leverage IntelliSense** for type-safe key positioning\n8. **Use helper functions** for additional validation and discovery\n\n### Troubleshooting\n\n#### Common Issues\n\n**Extension not appearing in formatted output:**\n- Check that your vendor is registered in `vendor-loader.ts`\n- Verify your extension keys follow the `x-vendor-name` format\n- Ensure your positioning functions return valid numbers\n\n**Extensions in wrong order:**\n- Use `before()` and `after()` helper functions for positioning\n- Check that referenced standard keys exist in the context\n- Verify your positioning logic is correct\n\n**Extension collisions:**\n- Use unique vendor prefixes to avoid conflicts\n- Check the console for collision warnings\n- Consider renaming conflicting extensions\n\n**Build errors:**\n- Ensure your TypeScript syntax is correct\n- Check that all imports are properly resolved\n- Verify your extension structure matches the expected format\n\n#### Debug Tips\n\n1. **Enable debug logging**: Set `DEBUG=prettier-plugin-openapi:*` environment variable\n2. **Check console output**: Look for collision warnings and error messages\n3. **Test with simple extensions**: Start with basic positioning before complex logic\n4. **Verify context names**: Ensure you're using the correct context names from the supported list\n\n### Example: Complete Vendor Extension\n\n```typescript\n/**\n * MyAPI Extensions\n * \n * MyAPI platform extensions for OpenAPI formatting.\n * Website: https://myapi.com\n */\n\nimport { defineConfig } from \"../index.js\";\n\nexport const myapi = defineConfig({\n  info: {\n    name: 'MyAPI',\n    website: 'https://myapi.com',\n    support: 'support@myapi.com'\n  },\n  extensions: {\n    'top-level': (before, after) =\u003e {\n      return {\n        'x-myapi-sdk': before('info'),\n        'x-myapi-version': after('info'),\n      };\n    },\n    'operation': (before, after) =\u003e {\n      return {\n        'x-myapi-rate-limit': before('parameters'),\n        'x-myapi-retries': after('parameters'),\n        'x-myapi-timeout': after('responses'),\n      };\n    },\n    'schema': (before, after) =\u003e {\n      return {\n        'x-myapi-validation': after('type'),\n        'x-myapi-example': after('example'),\n      };\n    }\n  }\n});\n```\n\n## Development\n\n### Modern Development Stack\n\nThis project uses modern development tools for optimal performance and developer experience:\n\n- **Bun** - Fast JavaScript runtime and package manager\n- **TypeScript** - Type-safe development with strict settings\n- **Biome** - Fast linting and formatting (replaces ESLint + Prettier for code)\n- **Prettier** - Documentation and configuration file formatting\n- **GitHub Actions** - Automated CI/CD with smart releases\n\n### Quick Start\n\n```bash\n# Install dependencies\nbun install\n\n# Build the plugin\nbun run build\n\n# Run tests\nbun test\n\n# Run tests with coverage\nbun test --coverage\n\n# Lint code\nbun run lint\n\n# Fix linting issues\nbun run lint:fix\n\n# Format code\nbun run format\n```\n\n### Available Scripts\n\n- `bun run dev` - Start development mode with TypeScript watch\n- `bun run build` - Build the project\n- `bun run test` - Run all tests\n- `bun run test:coverage` - Run tests with coverage report\n- `bun run test:watch` - Run tests in watch mode\n- `bun run lint` - Run Biome linting\n- `bun run lint:fix` - Fix Biome linting issues automatically\n- `bun run format` - Format code with Prettier\n- `bun run format:check` - Check code formatting\n- `bun run type-check` - Run TypeScript type checking\n- `bun run validate` - Run all validation checks (type-check, lint, test)\n- `bun run clean` - Clean build artifacts\n\n### Project Structure\n\n```\nsrc/\n  index.ts                    # Main plugin implementation\n  keys.ts                     # OpenAPI key definitions\n  extensions/\n    index.ts                  # Extension system\n    vendor-loader.ts          # Automatic vendor loading\n    vendor/                   # Vendor extensions\n      speakeasy.ts\n      postman.ts\n      redoc.ts\ntest/\n  plugin.test.ts              # Core plugin tests\n  integration.test.ts         # Integration tests\n  build.test.ts              # Build validation tests\n  coverage.test.ts            # Coverage enhancement tests\n  file-detection.test.ts      # File detection tests\n  key-ordering.test.ts        # Key sorting tests\n  custom-extensions.test.ts  # Extension tests\n  options.test.ts            # Configuration tests\n  simple-ordering.test.ts     # Basic ordering tests\n  vendor.test.ts             # Vendor extension tests\n  setup.ts                    # Test utilities\n```\n\n### Test Suite\n\nThe project includes a comprehensive test suite with **142 tests** covering:\n\n- **Core Functionality**: Plugin structure, parsing, formatting\n- **Integration Tests**: Real OpenAPI file processing, error handling\n- **Build Tests**: Package validation, TypeScript compilation\n- **Coverage Tests**: Edge cases, error scenarios\n- **File Detection**: OpenAPI file recognition, component files\n- **Key Ordering**: OpenAPI key sorting, custom extensions\n- **Vendor Extensions**: Extension system functionality\n- **Options**: Configuration and formatting options\n\n**Coverage**: 95.69% line coverage, 97.00% function coverage\n\n### CI/CD Pipeline\n\nThe project includes automated CI/CD with GitHub Actions:\n\n- **Continuous Integration**: Tests on Node.js 18, 20, 22 and Bun\n- **Automated Testing**: Linting with Biome, type checking, security audits\n- **Smart Releases**: Automatic patch version bumps on main branch updates\n- **NPM Publishing**: Automated publishing with version management\n- **Quality Gates**: All tests must pass before release\n\n## Configuration Options\n\nThe plugin respects standard Prettier options:\n\n- `tabWidth`: Number of spaces for indentation (default: 2)\n- `printWidth`: Maximum line length (default: 80)\n- `useTabs`: Use tabs instead of spaces (default: true)\n\n## Advanced Features\n\n### File Detection\n\nThe plugin intelligently detects OpenAPI files based on:\n\n1. **Content Structure**: Files with OpenAPI-specific keys (`openapi`, `swagger`, `components`, etc.)\n2. **Directory Patterns**: Files in OpenAPI-related directories (`components/`, `paths/`, `webhooks/`)\n3. **File Extensions**: Standard OpenAPI file extensions\n\n### Key Sorting Algorithm\n\nThe plugin uses a unified sorting algorithm that:\n\n1. **Prioritizes Standard Keys**: OpenAPI specification keys are sorted first\n2. **Handles Custom Extensions**: Vendor extensions are positioned relative to standard keys\n3. **Sorts Unknown Keys**: Non-standard keys are sorted alphabetically at the end\n4. **Context-Aware**: Different sorting rules for different OpenAPI contexts (operations, schemas, etc.)\n\n### Performance Optimizations\n\n- **Unified Sorting Function**: Single function handles all sorting scenarios\n- **Lazy Loading**: Vendor extensions are loaded only when needed\n- **Efficient Detection**: Fast file type detection with minimal overhead\n\n## Quality \u0026 Reliability\n\n### Comprehensive Testing\n\n- **142 Test Cases**: Covering all major functionality\n- **95.69% Line Coverage**: Extensive test coverage\n- **97.00% Function Coverage**: Nearly complete function testing\n- **Edge Case Testing**: Malformed files, error scenarios, performance\n- **Integration Testing**: Real-world OpenAPI file processing\n\n### Code Quality\n\n- **TypeScript**: Full type safety and IntelliSense support\n- **Biome**: Fast linting and formatting with TypeScript support\n- **Prettier**: Consistent code formatting\n- **Security Audits**: Automated dependency vulnerability scanning\n- **Performance Testing**: Large file handling and memory usage\n\n### CI/CD Pipeline\n\n- **Automated Testing**: Runs on every commit and PR\n- **Multi-Environment**: Tests on Node.js 18, 20, 22 and Bun\n- **Quality Gates**: All tests must pass before merge\n- **Smart Releases**: Automatic patch version management\n- **NPM Publishing**: Automated package publishing with proper versioning\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/your-feature-name`\n3. **Make your changes** with proper TypeScript types\n4. **Add tests** for new functionality (aim for 90%+ coverage)\n5. **Run the test suite**:\n   ```bash\n   bun test\n   bun run lint\n   bun run format\n   ```\n6. **Ensure all tests pass** (142 tests, 0 failures)\n7. **Submit a pull request** with a clear description\n\n### Development Guidelines\n\n- **Code Quality**: All code must pass Biome and Prettier checks\n- **Testing**: New features require comprehensive tests\n- **TypeScript**: Use proper types and interfaces\n- **Documentation**: Update README for new features\n- **CI/CD**: All GitHub Actions must pass before merge\n\n### Release Process\n\n- **Automatic**: Patch releases happen automatically on main branch updates\n- **Manual**: Major/minor releases require manual version bumps\n- **Quality Gates**: All tests, linting, and security checks must pass\n- **NPM Publishing**: Automated publishing with proper versioning\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Related Projects\n\n- [Prettier](https://prettier.io/) - The core formatter\n- [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0.html) - The OpenAPI specification\n- [Swagger](https://swagger.io/) - API development tools\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLukasParke%2Fprettier-plugin-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLukasParke%2Fprettier-plugin-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLukasParke%2Fprettier-plugin-openapi/lists"}