ehyiah / apidoc-bundle
Symfony Bundle to deal with api doc using SwaggerUI and yaml/yml files
Installs: 86
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 1
Forks: 1
Open Issues: 4
Type:symfony-bundle
Requires
- php: >=8.1
- doctrine/orm: ^2.10
- symfony/dependency-injection: ^6.1|^7.0
- symfony/finder: ^6.1|^7.0
- symfony/form: ^6.1|^7.0
- symfony/monolog-bundle: ^3.1
- symfony/property-access: ^6.1|^7.0
- symfony/property-info: ^6.1|^7.0
- symfony/yaml: ^6.1|^7.0
Requires (Dev)
- composer/composer: ^2.7@dev
- dg/bypass-finals: ^1.7
- friendsofphp/php-cs-fixer: ^3.48
- phpstan/extension-installer: ^1.3
- phpstan/phpstan: ^1.10
- phpstan/phpstan-symfony: ^1.3
- phpunit/phpunit: ^9.6
- symfony/framework-bundle: ^7.0|^6.1
- symfony/phpunit-bridge: ^7.1
This package is auto-updated.
Last update: 2025-07-17 07:15:18 UTC
README
Symfony Bundle to deal with api doc using SwaggerUI and yaml/yml files without annotations/attributes.
what this bundle does:
- display api doc with SwaggerUI
- generate some schemas, bodies and more to come with commands
If you just want to write simple yaml/yml files to create your api doc, this bundle is made for you. Install, create your api doc with yaml/yml files in the source directory, it's done! You can create as many files as you want and organize them in a subdirectory as well to your needs.
to write files Check the openapi specifications OpenApi
This bundle uses the Swagger UI to render the final result.
You will find some example after the bundle is installed in the default directory /src/Swagger.
Installation
Be sure that contrib recipes are allowed in your project
composer config extra.symfony.allow-contrib true
Then Run
composer require ehyiah/apidoc-bundle
Usage
-
In your .env file, update the site_urls variable to use it in your Swagger UI interface.
-
In the src/Swagger directory, add the YAML files that you want to be parsed and displayed on the Swagger UI interface. the directory can be modified in the .env file with the source_path variable.
-
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.
Recommended directory structure
If you want to use generation commands (see below) but do not want to use Auto-generated components names,
you will have to check and update all $ref used in the generated yaml/yml files by the commands.
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.
So if you want to call your component MyAwesomeDto instead of default name, you will have to update the reference ($ref) in every file.
{SOURCE_PATH} => is the env variable used as source directory for your api doc default is src/Swagger
| Type of Components | Default directory |
|---|---|
| Schemas | {SOURCE_PATH}/schemas |
Generating ApiDoc Components
Some commands are included in the bundle to pre-generate components. You will probably have to edit the generated files or at least check if everything is okay.
| Command | Arguments | Options | Generation type |
|---|---|---|---|
| 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 --skip (-s) list of properties to skip (you can pass multiple times this option to skip many properties) |
Generate a schema |
| 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 | Generate a RequestBody |
ApiDoc Linting
If needed, there is a command to generate your api doc into a single file in YAML or JSON format.
bin/console apidocbundle:api-doc:generate
You can use this command, for example, to generate a YAML file and use vacuum to lint your file.