PHPackages j835111/symfony-swagger-bundle - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. j835111/symfony-swagger-bundle ActiveSymfony-bundle[API Development](/categories/api) j835111/symfony-swagger-bundle ============================== Symfony Bundle for Swagger/OpenAPI documentation integration v1.4.4(2mo ago)02621MITPHPPHP >=8.1CI passing Since Jan 26Pushed 2mo agoCompare [ Source](https://github.com/j835111/symfony-swagger)[ Packagist](https://packagist.org/packages/j835111/symfony-swagger-bundle)[ Docs](https://github.com/j835111/symfony-swagger-bundle)[ RSS](/packages/j835111-symfony-swagger-bundle/feed)WikiDiscussions main Synced today READMEChangelogDependencies (30)Versions (13)Used By (0) Symfony Swagger Bundle ====================== [](#symfony-swagger-bundle) **Language:** English | [繁體中文](README.zh-TW.md) A Symfony bundle that automatically generates Swagger/OpenAPI 3.1 documentation from Symfony controller attributes. Features -------- [](#features) - Generate OpenAPI 3.1 documents automatically. - Read Symfony controller attributes such as `#[Route]`, `#[MapRequestPayload]`, `#[MapQueryParameter]`, `#[MapQueryString]`, and `#[MapUploadedFile]`. - Generate schemas from DTOs, union types, nullable types, enums, docblocks, Doctrine ORM attributes, and JMS serializer type hints. - Provide built-in documentation endpoints for OpenAPI JSON, Swagger UI, and Scalar API Reference. - Support request-level caching and Symfony Cache. - Detect circular schema references. - Add security schemes for endpoints using `#[IsGranted]`. - Customize response metadata with `#[ApiResponse]`. Requirements ------------ [](#requirements) - PHP >= 8.2 - Symfony ^6.0 or ^7.0 Installation ------------ [](#installation) Install the bundle with Composer: ``` composer require j835111/symfony-swagger-bundle ``` The bundle automatically: - loads default configuration, so a config file is optional; - registers built-in documentation routes: - `/api/docs.json` - `/api/docs` - `/api/docs/scalar` If you are not using Symfony Flex, register the bundle manually: ``` // config/bundles.php return [ // ... SymfonySwagger\SymfonySwaggerBundle::class => ['all' => true], ]; ``` Configuration ------------- [](#configuration) The bundle works with defaults out of the box. To customize it, create `config/packages/symfony_swagger.yaml`: ``` symfony_swagger: enabled: true info: title: 'My API' description: 'API Documentation' version: '1.0.0' servers: - url: 'https://api.example.com' description: 'Production server' - url: 'https://staging-api.example.com' description: 'Staging server' output_path: '%kernel.project_dir%/public/openapi.json' generation_mode: runtime cache: enabled: true ttl: 3600 analysis: max_depth: 5 include_internal_routes: false security: enabled: true default_scheme: defaultAuth security_schemes: defaultAuth: type: http scheme: bearer ``` Usage ----- [](#usage) After installation, the documentation endpoints are available immediately: ``` curl https://your-app.example/api/docs.json ``` Open the interactive documentation pages in a browser: - Swagger UI: `https://your-app.example/api/docs` - Scalar API Reference: `https://your-app.example/api/docs/scalar` Custom Documentation Controller ------------------------------- [](#custom-documentation-controller) If you need a custom endpoint, inject `OpenApiGenerator` into your own controller: ``` use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\Routing\Attribute\Route; use SymfonySwagger\Service\OpenApiGenerator; final class DocumentationController { public function __construct( private readonly OpenApiGenerator $openApiGenerator, ) { } #[Route('/internal/openapi.json', methods: ['GET'])] public function documentation(): JsonResponse { return new JsonResponse($this->openApiGenerator->generate()); } } ``` Controller Example ------------------ [](#controller-example) The bundle inspects Symfony controller attributes and method signatures: ``` use Symfony\Component\HttpKernel\Attribute\MapQueryParameter; use Symfony\Component\HttpKernel\Attribute\MapRequestPayload; use Symfony\Component\Routing\Attribute\Route; final class PostController { #[Route('/api/posts', methods: ['GET'])] public function list( #[MapQueryParameter] int $page = 1, #[MapQueryParameter] int $limit = 10, ): PostCollection { // Generates: // - path: /api/posts // - method: GET // - query parameters: page, limit // - response schema: PostCollection } #[Route('/api/posts', methods: ['POST'])] public function create( #[MapRequestPayload] CreatePostDto $dto, ): Post { // Generates: // - requestBody schema: CreatePostDto // - response schema: Post } #[Route('/api/posts/{id}', methods: ['GET'])] public function show(int $id): Post { // Generates: // - path parameter: id // - response schema: Post } } ``` Response Metadata ----------------- [](#response-metadata) Use `#[ApiResponse]` when the return type is not enough to describe the API response: ``` use Symfony\Component\HttpFoundation\BinaryFileResponse; use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\Routing\Attribute\Route; use SymfonySwagger\Attribute\ApiResponse; final class UserController { #[Route('/api/users/{id}', methods: ['GET'])] #[ApiResponse(type: UserResponse::class)] public function show(string $id): JsonResponse { // Response envelope: // { code: int, message: string, data: UserResponse } } #[Route('/api/users/export', methods: ['GET'])] #[ApiResponse(file: true, fileMediaType: 'text/csv')] public function export(): BinaryFileResponse { // Generates a binary file response schema. } } ``` DTO Example ----------- [](#dto-example) ``` final class CreatePostDto { public string $title; public string $content; public ?string $excerpt = null; public Status $status; public AuthorDto $author; /** @var string[] */ public array $tags; } enum Status: string { case DRAFT = 'draft'; case PUBLISHED = 'published'; } ``` The generated schema includes required fields, nullable fields, enum values, nested DTO references, and array item types inferred from docblocks. Development ----------- [](#development) Install dependencies: ``` composer install ``` Run tests: ``` vendor/bin/phpunit ``` Run static analysis and style checks: ``` vendor/bin/phpstan analyse vendor/bin/php-cs-fixer fix --dry-run --diff ``` Or run the project analysis script: ``` composer analyze ``` Project Structure ----------------- [](#project-structure) ``` symfony-swagger/ ├── src/ │ ├── SymfonySwaggerBundle.php │ ├── DependencyInjection/ │ ├── Controller/ │ ├── Routing/ │ ├── Service/ │ ├── Analyzer/ │ └── Attribute/ ├── config/ │ ├── packages/ │ ├── routes/ │ └── services.php ├── tests/ ├── docs/ └── composer.json ``` Contributing ------------ [](#contributing) Issues and pull requests are welcome. License ------- [](#license) MIT License Links ----- [](#links) - [Symfony Documentation](https://symfony.com/doc/current/index.html) - [OpenAPI Specification](https://swagger.io/specification/) - [Symfony Bundle Best Practices](https://symfony.com/doc/current/bundles/best_practices.html) ### Health Score 43 — FairBetter than 89% of packages Maintenance87 Actively maintained with recent releases Popularity16 Limited adoption so far Community11 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 60% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~9 days Recently: every ~4 days Total 11 Last Release 63d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/19169126?v=4)[j835111](/maintainers/j835111)[@j835111](https://github.com/j835111) --- Top Contributors [![j835111fornxn](https://avatars.githubusercontent.com/u/233662701?v=4)](https://github.com/j835111fornxn "j835111fornxn (21 commits)")[![JamesForWork](https://avatars.githubusercontent.com/u/102041402?v=4)](https://github.com/JamesForWork "JamesForWork (7 commits)")[![NxnChing](https://avatars.githubusercontent.com/u/229283378?v=4)](https://github.com/NxnChing "NxnChing (5 commits)")[![j835111](https://avatars.githubusercontent.com/u/19169126?v=4)](https://github.com/j835111 "j835111 (2 commits)") --- Tags openapisymfony-bundleapisymfonydocumentationswaggeropenapi ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/j835111-symfony-swagger-bundle/health.svg) ``` [![Health](https://phpackages.com/badges/j835111-symfony-swagger-bundle/health.svg)](https://phpackages.com/packages/j835111-symfony-swagger-bundle) ``` ### Alternatives [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k5.9M738](/packages/sylius-sylius)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 585.6M574](/packages/shopware-core)[oro/platform Business Application Platform (BAP) 645143.5k115](/packages/oro-platform)[easycorp/easyadmin-bundle Admin generator for Symfony applications 4.3k17.9M386](/packages/easycorp-easyadmin-bundle)[2lenet/crudit-bundle The easy like Crud'it Bundle. 1616.4k14](/packages/2lenet-crudit-bundle)[shopware/platform The Shopware e-commerce core 3.4k1.5M3](/packages/shopware-platform) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)