{"id":16770821,"url":"https://github.com/ehyiah/apidocbundle","last_synced_at":"2025-12-29T15:57:46.963Z","repository":{"id":242040066,"uuid":"807087409","full_name":"Ehyiah/ApiDocBundle","owner":"Ehyiah","description":"symfony bundle to deal with api doc and swagger UI","archived":false,"fork":false,"pushed_at":"2025-07-16T08:35:51.000Z","size":124,"stargazers_count":2,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-16T09:47:48.547Z","etag":null,"topics":["apidoc","openapi","symfony"],"latest_commit_sha":null,"homepage":"","language":"PHP","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/Ehyiah.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-05-28T13:08:08.000Z","updated_at":"2025-07-16T08:35:54.000Z","dependencies_parsed_at":"2024-06-14T14:12:35.759Z","dependency_job_id":null,"html_url":"https://github.com/Ehyiah/ApiDocBundle","commit_stats":null,"previous_names":["ehyiah/apidocbundle"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/Ehyiah/ApiDocBundle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ehyiah%2FApiDocBundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ehyiah%2FApiDocBundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ehyiah%2FApiDocBundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ehyiah%2FApiDocBundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ehyiah","download_url":"https://codeload.github.com/Ehyiah/ApiDocBundle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ehyiah%2FApiDocBundle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271752126,"owners_count":24814750,"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","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"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":["apidoc","openapi","symfony"],"created_at":"2024-10-13T06:25:37.460Z","updated_at":"2025-12-29T15:57:46.957Z","avatar_url":"https://github.com/Ehyiah.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ApiDocBundle\nSymfony Bundle to deal with API documentation using multiple UI options with **YAML files** or **PHP classes**.\n\n## What this bundle does\n- Display API documentation with Swagger UI, Redoc, Stoplight Elements, RapiDoc or Scalar\n- Generate schemas, request bodies and more via commands (currently WIP, only supports YAML dump file)\n- Support both YAML and PHP configuration (or mix both!)\n\nIf you want to write simple YAML files to create your API doc, this bundle is made for you.\nOr, if you prefer a programmatic approach with PHP classes and IDE autocompletion, we've got you covered too!\n\nInstall, create your API doc with YAML files or PHP configuration classes, and you're done!\nYou can create as many files/classes as you want and organize them to your needs.\n\nTo write YAML files, check the OpenAPI specifications: [OpenApi](https://swagger.io/specification/v3/)\n\nThis bundle uses [Swagger UI](https://swagger.io/tools/swagger-ui/), [Redoc](https://redocly.com/redoc), [Stoplight Elements](https://stoplight.io/open-source/elements), [RapiDoc](https://rapidocweb.com/) or [Scalar](https://scalar.com/) to render the final result.\n\nYou will find examples after the bundle is installed in the default directory /src/Swagger.\n\n---\n- [Installation](#installation)\n- [Configuration](#configuration)\n  - [UI Selection](#ui-selection)\n- [Usage](#usage)\n  - [YAML Configuration](#yaml-configuration)\n  - [PHP Configuration Classes](#php-configuration-classes)\n  - [IDE Navigation with ApiDoc Attribute](#ide-navigation-with-apidoc-attribute)\n- [Components generation via commands](#generating-apidoc-components)\n---\n\n\n# Installation\nBe sure that contrib recipes are allowed in your project \n```sh\n    composer config extra.symfony.allow-contrib true\n```\n\nThen Run \n```sh\n  composer require ehyiah/apidoc-bundle\n```\n\n# Configuration\n\n## UI Selection\n\nThis bundle supports five documentation UIs:\n\n| UI | Value | Description | Try it out | Links |\n|:---|:------|:------------|:-----------|:------|\n| **Swagger UI** | `swagger` | The standard, widely used | ✅ Yes | [GitHub](https://github.com/swagger-api/swagger-ui) - [Demo](https://petstore.swagger.io/) |\n| **Redoc** | `redoc` | Clean, elegant 3-column layout | ❌ No | [GitHub](https://github.com/Redocly/redoc) - [Demo](https://redocly.github.io/redoc/) |\n| **Stoplight Elements** | `stoplight` | Modern, customizable | ✅ Yes | [GitHub](https://github.com/stoplightio/elements) - [Demo](https://elements-demo.stoplight.io/) |\n| **RapiDoc** | `rapidoc` | Lightweight, dark/light themes | ✅ Yes | [GitHub](https://github.com/rapi-doc/RapiDoc) - [Demo](https://rapidocweb.com/examples.html) |\n| **Scalar** | `scalar` | Beautiful, modern design | ✅ Yes | [GitHub](https://github.com/scalar/scalar) - [Demo](https://docs.scalar.com/swagger-editor) |\n\n### Default UI\n\nConfigure the default UI in your bundle configuration (`config/packages/ehyiah_api_doc.yaml`):\n\n```yaml\nehyiah_api_doc:\n    ui: swagger  # swagger, redoc, stoplight, rapidoc or scalar\n```\n\n### Switching UI via Query Parameter\n\nYou can switch between UIs on the fly using the `ui` query parameter:\n\n- `/api/doc` → Uses the default UI (from config)\n- `/api/doc?ui=swagger` → Swagger UI\n- `/api/doc?ui=redoc` → Redoc\n- `/api/doc?ui=stoplight` → Stoplight Elements\n- `/api/doc?ui=rapidoc` → RapiDoc\n- `/api/doc?ui=scalar` → Scalar\n\nThis is useful if you want to use one UI for public documentation and another for testing API calls.\n\n---\n\n# Usage\n\n## YAML Configuration\n\n- In your .env file, you can update the site_urls variable to use it in your Swagger UI interface (or define yourself via PHP classes or directly inside YAML files)\n\n- In the src/Swagger (default directory) directory, add the YAML files that you want to be parsed and displayed on the Swagger UI interface.\n**the directory can be modified in the .env file with the source_path variable.**\n\n- the default route is ehyiah/api/doc example: localhost/ehyiah/api/doc, **you can modify this route in the config/routes/ehyiah_api_doc.yaml file.**\n\n## PHP Configuration Classes\n\nYou can define your API documentation using PHP classes instead of (or in addition to) YAML files!\n\n### Quick Example\n\n```php\n\u003c?php\nnamespace App\\ApiDoc;\n\nuse Ehyiah\\ApiDocBundle\\Builder\\ApiDocBuilder;\nuse Ehyiah\\ApiDocBundle\\Interfaces\\ApiDocConfigInterface;\n\nclass UserApiDocConfig implements ApiDocConfigInterface\n{\n    public function configure(ApiDocBuilder $builder): void\n    {\n        $builder\n            -\u003eaddRoute()\n                -\u003epath('/api/users/{id}')\n                -\u003emethod('GET')\n                -\u003esummary('Get user by ID')\n                -\u003etag('Users')\n                -\u003eparameter()\n                    -\u003ename('id')\n                    -\u003ein('path')\n                    -\u003erequired()\n                    -\u003eschema(['type' =\u003e 'integer'])\n                -\u003eend()\n                -\u003eresponse(200)\n                    -\u003edescription('User found')\n                    -\u003ejsonContent()\n                        -\u003eref('#/components/schemas/User')\n                    -\u003eend()\n                -\u003eend()\n            -\u003eend();\n    }\n}\n```\n\n### Learn More\n\n📚 **See [docs/PHP_CONFIG_CLASSES.md](docs/PHP_CONFIG_CLASSES.md) for complete documentation with examples.**\n\n### Benefits\n\n- ✅ **Type safety** - IDE autocompletion and type hints\n- ✅ **Flexible** - Generate documentation dynamically\n- ✅ **Reusable** - Share common patterns across routes\n- ✅ **Hybrid** - Works alongside YAML files\n\n## IDE Navigation with ApiDoc Attribute\n\nTo improve navigation between your controllers and their API documentation, you can use the `#[ApiDoc]` attribute.\nThis attribute creates a direct link from your controller methods to the PHP configuration class where the documentation is defined.\n\n**Ctrl+Click** on the class reference in your IDE to navigate directly to the documentation!\n\n```php\n\u003c?php\nnamespace App\\Controller;\n\nuse Ehyiah\\ApiDocBundle\\Attributes\\ApiDoc;\nuse App\\ApiDoc\\UserApiDocConfig;\n\nclass UserController\n{\n    #[ApiDoc(UserApiDocConfig::class)]\n    public function getUser(int $id): Response\n    {\n        // Ctrl+Click on UserApiDocConfig::class to navigate to the documentation\n    }\n\n    // You can also reference a specific method in the config class\n    #[ApiDoc(UserApiDocConfig::class, 'configureCreateUser')]\n    public function createUser(Request $request): Response\n    {\n        // ...\n    }\n}\n```\n\nThis attribute is purely for IDE navigation - it has no runtime behavior but makes it easy to find and maintain your API documentation.\n\n## YAML Directory Structure\n\n## Recommended directory structure\nIf you want to use generation commands (see below) but do not want to use Auto-generated components names, \nyou will have to check and update all ``$ref`` used in the generated yaml/yml files by the commands.\n\n**Exemple**: You got a DTO class called ``MyDto``, a schema named ``MyDto`` will be created and used everywhere a reference to this class is created. \nSo if you want to call your component ``MyAwesomeDto`` instead of default name, you will have to update the reference (``$ref``) in every file.\n\n```{SOURCE_PATH}``` =\u003e is the env variable used as source directory for your api doc default is ```src/Swagger```\n\n| Type of Components |   Default directory   |\n|:------------------:|:---------------------:|\n|      Schemas       | {SOURCE_PATH}/schemas |\n|                    |                       |\n\n\n# Generating ApiDoc Components (WIP)\nSome commands are included in the bundle to pre-generate components.\nYou will probably have to edit the generated files or at least check if everything is okay.\n\n| Command                       | Arguments                                                                                   | Options                                                                                                                                                                                                                          | Generation type                                                                          |\n|:------------------------------|:--------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------|\n| apidocbundle:component:schema | pass the FQCN of the php class you wish (exemple: a DTO, an Entity, any POPO)               | **--output** (-o) specify a custom output directory to dump the generated file from the kernel_project_dir\u003cbr/\u003e **--skip** (-s) list of properties to skip _(you can pass multiple times this option to skip many properties)_ **--format** (-f) output format: `yaml`, `php`, or `both` (default: `yaml`)  | Generate a [schema](https://swagger.io/specification/v3/#schema-object)                  |\n| apidocbundle:component:body   | pass the FQCN of the php class you wish (exemple: a DTO, an Entity, any POPO or a FormType) | **--reference** (-r) specify if a reference must be used instead of regenerating a new schema in the requestBody **--format** (-f) output format: `yaml`, `php`, or `both` (default: `yaml`)                                                                                                               | Generate a [RequestBody](https://swagger.io/docs/specification/describing-request-body/) |\n| apidocbundle:route:generate   | **route**: Chemin de la route (exemple: /api/users)\u003cbr/\u003e**method**: Méthode HTTP (GET, POST, PUT, DELETE...) | **--tag** (-t) Tags à associer à la route\u003cbr/\u003e**--description** (-d) Description de la route\u003cbr/\u003e**--response-schema** (-rs) Nom du schéma à utiliser pour la réponse\u003cbr/\u003e**--request-body** (-rb) Nom du requestBody à utiliser\u003cbr/\u003e**--output** (-o) Répertoire de sortie\u003cbr/\u003e**--filename** (-f) Nom du fichier à générer | Generate a [Path Item Object](https://swagger.io/specification/v3/#path-item-object)     |\n\n### Output Format\n\nYou can choose the output format using the `--format` option:\n\n```bash\n# Generate PHP file (default)\nbin/console apidocbundle:component:schema \"App\\DTO\\UserDTO\"\n\nOR bin/console apidocbundle:component:schema \"App\\DTO\\UserDTO\" --format=php\n\n# Generate YAML file\nbin/console apidocbundle:component:schema \"App\\DTO\\UserDTO\" --format=yaml\n\n# Generate both YAML and PHP files\nbin/console apidocbundle:component:schema \"App\\DTO\\UserDTO\" --format=both\n```\n\n### Duplicate Component Detection\n\nWhen generating a component, the command will automatically check if a component with the same name already exists in your codebase:\n\n1. **Same format exists**: If you're generating a YAML file and a YAML file with the same component already exists (or PHP for PHP), you will be prompted to confirm if you want to overwrite it.\n\n2. **Different format exists**: If you're generating a YAML file but a PHP file with the same component already exists (or vice versa), you will be warned about potential duplicate definitions and asked to confirm before continuing.\n\n**Example output:**\n```\nComponent already exists in YAML file: /path/to/schemas/UserDTO.yaml\nDo you want to overwrite this file with new values ? (yes or no, default is YES)\n\nComponent also exists in PHP file: /path/to/schemas/UserDTO.php\nDo you want to continue generating the YAML file? This may cause duplicate definitions. (yes or no, default is YES)\n```\n\nThis helps prevent accidental overwrites and warns you about duplicate component definitions that could cause conflicts in your API documentation.\n\n\n# ApiDoc Linting\nIf needed, there is a command to generate your api doc into a single file in YAML or JSON format.\n\n``` bin/console apidocbundle:api-doc:generate ```\n\nYou can use this command, for example, to generate a YAML file and use [vacuum](https://quobix.com/vacuum/api/getting-started) to lint your file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehyiah%2Fapidocbundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehyiah%2Fapidocbundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehyiah%2Fapidocbundle/lists"}