{"id":50931842,"url":"https://github.com/monkeyscloud/monkeyslegion-openapi","last_synced_at":"2026-06-17T05:04:00.701Z","repository":{"id":360330389,"uuid":"1207354189","full_name":"MonkeysCloud/MonkeysLegion-OpenApi","owner":"MonkeysCloud","description":"Automatic OpenAPI 3.1 specification generator and documentation middleware for the MonkeysLegion framework.","archived":false,"fork":false,"pushed_at":"2026-04-21T10:12:37.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T02:11:10.167Z","etag":null,"topics":["open-api","openapi","php","php-framework"],"latest_commit_sha":null,"homepage":"https://monkeyslegion.com/","language":"PHP","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/MonkeysCloud.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":"2026-04-10T21:09:56.000Z","updated_at":"2026-04-11T02:25:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MonkeysCloud/MonkeysLegion-OpenApi","commit_stats":null,"previous_names":["monkeyscloud/monkeyslegion-openapi"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/MonkeysCloud/MonkeysLegion-OpenApi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MonkeysCloud%2FMonkeysLegion-OpenApi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MonkeysCloud%2FMonkeysLegion-OpenApi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MonkeysCloud%2FMonkeysLegion-OpenApi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MonkeysCloud%2FMonkeysLegion-OpenApi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MonkeysCloud","download_url":"https://codeload.github.com/MonkeysCloud/MonkeysLegion-OpenApi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MonkeysCloud%2FMonkeysLegion-OpenApi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34434496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"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":["open-api","openapi","php","php-framework"],"created_at":"2026-06-17T05:03:59.850Z","updated_at":"2026-06-17T05:04:00.697Z","avatar_url":"https://github.com/MonkeysCloud.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MonkeysLegion OpenAPI\n\nAutomatic **OpenAPI 3.1** specification generator and documentation middleware for the [MonkeysLegion](https://github.com/MonkeysCloud) framework.\n\nGenerate a complete API specification from your route definitions and PHP 8.4 attributes — zero manual YAML/JSON editing required.\n\n---\n\n## Features\n\n| Feature | Description |\n|---|---|\n| **Attribute-driven** | Annotate controllers with `#[ApiParam]`, `#[ApiResponse]`, `#[RequestBody]`, `#[ApiSecurity]`, `#[ApiDeprecated]`, `#[ApiHidden]` |\n| **Auto parameter detection** | Path parameters like `{id}` are automatically documented |\n| **Security schemes** | Bearer JWT, API key, OAuth2 — configurable per-controller or per-method |\n| **Multiple responses** | Document 200, 404, 422, etc. with schemas per endpoint |\n| **Request body schemas** | Inline JSON Schema or `$ref` to DTO classes |\n| **Swagger UI + ReDoc** | Built-in middleware serves either documentation UI |\n| **Dark mode** | Optional dark theme for Swagger UI |\n| **Caching** | Spec is cached after first build; invalidate on demand |\n| **YAML export** | `toYaml()` when `ext-yaml` is available |\n| **Enable/disable** | Toggle docs off in production with a single flag |\n\n---\n\n## Installation\n\n```bash\ncomposer require monkeyscloud/monkeyslegion-openapi\n```\n\n### Requirements\n\n- PHP 8.4+\n- `monkeyscloud/monkeyslegion-router` ^2.0\n- `monkeyscloud/monkeyslegion-http` ^2.0\n\n---\n\n## Quick Start\n\n### 1. Annotate your controller\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nnamespace App\\Controllers;\n\nuse MonkeysLegion\\OpenApi\\Attributes\\ApiInfo;\nuse MonkeysLegion\\OpenApi\\Attributes\\ApiParam;\nuse MonkeysLegion\\OpenApi\\Attributes\\ApiResponse;\nuse MonkeysLegion\\OpenApi\\Attributes\\ApiSecurity;\nuse MonkeysLegion\\OpenApi\\Attributes\\RequestBody;\nuse MonkeysLegion\\Router\\Attributes\\Route;\n\n#[ApiInfo(\n    title: 'User Service API',\n    version: '2.0.0',\n    description: 'Manages user accounts and profiles.',\n    contactName: 'MonkeysCloud Team',\n    contactEmail: 'support@monkeys.cloud',\n)]\n#[ApiSecurity('bearerAuth')]\nfinal class UserController\n{\n    #[Route('GET', '/users', name: 'user_list', summary: 'List users', tags: ['Users'])]\n    #[ApiParam(name: 'page', in: 'query', type: 'integer', example: 1)]\n    #[ApiParam(name: 'per_page', in: 'query', type: 'integer', example: 25, required: false)]\n    #[ApiResponse(200, 'User list', schema: [\n        'type' =\u003e 'array',\n        'items' =\u003e ['$ref' =\u003e '#/components/schemas/User'],\n    ])]\n    public function index(): ResponseInterface { /* ... */ }\n\n    #[Route('GET', '/users/{id:\\d+}', name: 'user_show', summary: 'Get user', tags: ['Users'])]\n    #[ApiParam(name: 'id', in: 'path', type: 'integer')]\n    #[ApiResponse(200, 'User found')]\n    #[ApiResponse(404, 'User not found')]\n    public function show(int $id): ResponseInterface { /* ... */ }\n\n    #[Route('POST', '/users', name: 'user_create', summary: 'Create user', tags: ['Users'])]\n    #[RequestBody(\n        description: 'User creation payload',\n        schema: [\n            'type' =\u003e 'object',\n            'properties' =\u003e [\n                'name'  =\u003e ['type' =\u003e 'string'],\n                'email' =\u003e ['type' =\u003e 'string', 'format' =\u003e 'email'],\n            ],\n            'required' =\u003e ['name', 'email'],\n        ],\n    )]\n    #[ApiResponse(201, 'User created')]\n    #[ApiResponse(422, 'Validation error')]\n    public function create(): ResponseInterface { /* ... */ }\n}\n```\n\n### 2. Register the middleware\n\n```php\nuse MonkeysLegion\\OpenApi\\OpenApiGenerator;\nuse MonkeysLegion\\OpenApi\\OpenApiMiddleware;\n\n$generator = new OpenApiGenerator(\n    routes: $routeCollection,\n    title: 'My API',\n    version: '1.0.0',\n    servers: [\n        ['url' =\u003e 'https://api.example.com', 'description' =\u003e 'Production'],\n        ['url' =\u003e 'http://localhost:8080',    'description' =\u003e 'Local'],\n    ],\n);\n\n// Add to your middleware pipeline\n$handler-\u003epipe(new OpenApiMiddleware(\n    generator: $generator,\n    jsonPath:  '/openapi.json',    // JSON spec endpoint\n    uiPath:    '/docs',            // Swagger UI / ReDoc endpoint\n    uiTheme:   'swagger',         // 'swagger' or 'redoc'\n    darkMode:  false,              // dark Swagger UI theme\n    enabled:   true,               // set false in production\n));\n```\n\n### 3. Access your docs\n\n- **JSON spec**: `GET /openapi.json`\n- **Swagger UI**: `GET /docs`\n\n---\n\n## Attributes Reference\n\n### `#[ApiInfo]` — Controller class\n\nDefines API-level metadata. Place on the controller class.\n\n```php\n#[ApiInfo(\n    title: 'My API',\n    version: '2.0.0',\n    description: 'API description',\n    contactName: 'Team',\n    contactEmail: 'team@example.com',\n    contactUrl: 'https://example.com',\n    licenseName: 'MIT',\n    licenseUrl: 'https://opensource.org/licenses/MIT',\n    termsOfService: 'https://example.com/tos',\n)]\n```\n\n### `#[ApiParam]` — Method (repeatable)\n\nDocuments a path, query, header, or cookie parameter.\n\n```php\n#[ApiParam(\n    name: 'id',\n    in: 'path',           // 'path', 'query', 'header', 'cookie'\n    type: 'integer',       // JSON Schema type\n    format: 'int64',       // JSON Schema format\n    required: true,\n    description: 'The user ID',\n    example: 42,\n    deprecated: false,\n)]\n```\n\n\u003e **Note:** Path parameters from route templates (e.g., `{id}`) are **auto-detected** if not explicitly annotated.\n\n### `#[ApiResponse]` — Method (repeatable)\n\nDocuments a response for a specific status code.\n\n```php\n#[ApiResponse(\n    status: 200,\n    description: 'Success',\n    contentType: 'application/json',\n    schema: ['type' =\u003e 'object', 'properties' =\u003e [...]],\n    headers: ['X-Request-Id' =\u003e ['schema' =\u003e ['type' =\u003e 'string']]],\n)]\n```\n\n### `#[RequestBody]` — Method\n\nDocuments the request body and its schema.\n\n```php\n#[RequestBody(\n    description: 'User data',\n    required: true,\n    contentType: 'application/json',\n    schema: ['type' =\u003e 'object', ...],\n    ref: App\\DTO\\CreateUserDto::class,  // alternative: reference a DTO\n)]\n```\n\n### `#[ApiSecurity]` — Class or Method (repeatable)\n\nDeclares security requirements.\n\n```php\n#[ApiSecurity('bearerAuth')]\n#[ApiSecurity('oauth2', scopes: ['users:read', 'users:write'])]\n```\n\n### `#[ApiDeprecated]` — Method\n\nMarks an endpoint as deprecated in the spec.\n\n```php\n#[ApiDeprecated('Use PATCH /v2/users/{id} instead.')]\n```\n\n### `#[ApiHidden]` — Method\n\nExcludes an endpoint from the generated specification entirely.\n\n```php\n#[ApiHidden]\n```\n\n---\n\n## Generator API\n\n```php\n$generator = new OpenApiGenerator(\n    routes: $routeCollection,\n    title: 'My API',\n    version: '1.0.0',\n    description: 'Optional description',\n    servers: [['url' =\u003e 'https://api.example.com']],\n    securitySchemes: [\n        'bearerAuth' =\u003e [\n            'type'         =\u003e 'http',\n            'scheme'       =\u003e 'bearer',\n            'bearerFormat' =\u003e 'JWT',\n        ],\n        'apiKey' =\u003e [\n            'type' =\u003e 'apiKey',\n            'in'   =\u003e 'header',\n            'name' =\u003e 'X-API-Key',\n        ],\n    ],\n);\n\n// Get as PHP array\n$spec = $generator-\u003etoArray();\n\n// Get as JSON\n$json = $generator-\u003etoJson();\n\n// Get as YAML (requires ext-yaml)\n$yaml = $generator-\u003etoYaml();\n\n// Clear cached spec\n$generator-\u003einvalidate();\n```\n\n---\n\n## Middleware Options\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `generator` | `OpenApiGenerator` | — | Required. The spec generator. |\n| `jsonPath` | `string` | `/openapi.json` | URI path for the JSON spec. |\n| `uiPath` | `string` | `/docs` | URI path for the documentation UI. |\n| `uiTheme` | `string` | `'swagger'` | `'swagger'` or `'redoc'`. |\n| `darkMode` | `bool` | `false` | Enable dark Swagger UI theme. |\n| `enabled` | `bool` | `true` | Set `false` to disable docs in production. |\n\n---\n\n## Testing\n\n```bash\ncomposer test\n```\n\n31 tests, 69 assertions covering:\n- Spec generation (version, info, paths, operations)\n- All 7 attributes\n- Parameter auto-detection\n- Request body, responses, security, deprecated, hidden\n- Middleware (Swagger UI, ReDoc, passthrough, disabled)\n- Caching and invalidation\n\n---\n\n## License\n\nMIT © [MonkeysCloud](https://monkeys.cloud)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkeyscloud%2Fmonkeyslegion-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonkeyscloud%2Fmonkeyslegion-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkeyscloud%2Fmonkeyslegion-openapi/lists"}