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.3.0(1mo ago)0651MITPHPPHP >=8.1CI failing Since Jan 26Pushed 1mo 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 1mo ago READMEChangelogDependencies (15)Versions (8)Used By (0) Symfony Swagger Bundle ====================== [](#symfony-swagger-bundle) 一個用於 Symfony 應用程式的 Swagger/OpenAPI 文件自動產生套件。 功能特色 ---- [](#功能特色) - ✅ 自動產生 OpenAPI 3.1 規格文件 - ✅ 從 Symfony Controller Attributes 自動生成文檔 - ✅ 支援 PHP 8.1+ Attributes (Route, MapRequestPayload, MapQueryParameter 等) - ✅ 智能型別分析 (支援 DTO、Union Types、Nullable Types、Enum) - ✅ 多層快取機制 (Request + Symfony Cache) - ✅ Schema 自動生成與循環引用偵測 - ✅ 與 Symfony 6/7 相容 - ✅ 遵循 Symfony Bundle 最佳實踐 系統需求 ---- [](#系統需求) - PHP >= 8.1 - Symfony >= 6.0 安裝 -- [](#安裝) 使用 Composer 安裝套件: ``` composer require your-vendor/symfony-swagger-bundle ``` Bundle 會自動: - 載入預設設定 (無需手動建立設定檔) - 自動註冊內建文件路由到 `/api/docs.json`、`/api/docs`、`/api/docs/scalar` > **注意**: 如果你沒有使用 Symfony Flex,需要手動註冊 Bundle: > > ``` > // config/bundles.php > return [ > // ... > SymfonySwagger\SymfonySwaggerBundle::class => ['all' => true], > ]; > ``` 自訂設定 (選填) --------- [](#自訂設定-選填) 預設情況下,套件會自動運作。如果需要自訂設定,建立 `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/swagger.json' # 快取設定 cache: enabled: true ttl: 3600 # 快取時間(秒) # 分析設定 analysis: max_depth: 5 # DTO 遞迴分析最大深度 include_internal_routes: false # 是否包含內部路由 (_profiler 等) ``` 使用方式 ---- [](#使用方式) ### 立即可用 [](#立即可用) 安裝後,API 文件端點立即可用: ``` curl https://your-app.com/api/docs.json ``` ### 自訂 Controller (選填) [](#自訂-controller-選填) 如果你需要自訂文件端點,可以建立自己的 Controller: ``` use SymfonySwagger\Service\OpenApiGenerator; class DocumentationController { public function __construct( private OpenApiGenerator $openApiGenerator ) { } #[Route('/api/docs.json', methods: ['GET'])] public function documentation(): Response { $openApiDoc = $this->openApiGenerator->generate(); return $this->json($openApiDoc); } } ``` ### Controller 範例 [](#controller-範例) Bundle 會自動從 Symfony Controller Attributes 生成文檔: ``` use Symfony\Component\HttpKernel\Attribute\MapRequestPayload; use Symfony\Component\HttpKernel\Attribute\MapQueryParameter; use Symfony\Component\Routing\Attribute\Route; class PostController { #[Route('/api/posts', methods: ['GET'])] public function list( #[MapQueryParameter] int $page = 1, #[MapQueryParameter] int $limit = 10 ): PostCollection { // 自動生成 OpenAPI: // - path: /api/posts // - method: GET // - parameters: page (query, integer), limit (query, integer) // - response: PostCollection schema } #[Route('/api/posts', methods: ['POST'])] public function create( #[MapRequestPayload] CreatePostDto $dto ): Post { // 自動生成 OpenAPI: // - requestBody: CreatePostDto schema // - response: Post schema } #[Route('/api/posts/{id}', methods: ['GET'])] public function show(int $id): Post { // 自動生成 OpenAPI: // - path parameter: id (integer) // - response: Post schema } } ``` ### DTO 範例 [](#dto-範例) ``` class CreatePostDto { public string $title; public string $content; public ?string $excerpt = null; public Status $status; // Enum 支援 public AuthorDto $author; // 巢狀物件 /** @var string[] */ public array $tags; # 從 DocBlock 推導陣列元素型別 } enum Status: string { case DRAFT = 'draft'; case PUBLISHED = 'published'; } // 自動生成的 Schema: // - CreatePostDto (object) // - title (string, required) // - content (string, required) // - excerpt (string, nullable) // - status (string, enum: [draft, published]) // - author ($ref: #/components/schemas/AuthorDto) // - tags (array of string) ``` 開發 -- [](#開發) ### 執行測試 [](#執行測試) ``` composer install vendor/bin/phpunit ``` ### 程式碼格式檢查 [](#程式碼格式檢查) ``` vendor/bin/php-cs-fixer fix ``` 目錄結構 ---- [](#目錄結構) ``` symfony-swagger/ ├── src/ │ ├── SymfonySwaggerBundle.php │ ├── DependencyInjection/ │ │ ├── Configuration.php │ │ └── SymfonySwaggerExtension.php │ ├── Controller/ │ │ └── SwaggerDocController.php │ ├── Service/ │ │ ├── OpenApiGenerator.php │ │ ├── Describer/ │ │ └── Registry/ │ ├── Analyzer/ │ └── Command/ ├── config/ │ └── services.php ├── tests/ ├── docs/ └── composer.json ``` 貢獻 -- [](#貢獻) 歡迎提交 Issue 和 Pull Request! 授權 -- [](#授權) MIT License 相關連結 ---- [](#相關連結) - [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 91% of packages Maintenance90 Actively maintained with recent releases Popularity14 Limited adoption so far Community11 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 65.4% 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 ~10 days Total 6 Last Release 49d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/1c807c6644a720121239fc533b67a422d3a5588001534e7ee5c733dfcfede338?d=identicon)[j835111](/maintainers/j835111) --- Top Contributors [![j835111fornxn](https://avatars.githubusercontent.com/u/233662701?v=4)](https://github.com/j835111fornxn "j835111fornxn (17 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)")[![JamesForWork](https://avatars.githubusercontent.com/u/102041402?v=4)](https://github.com/JamesForWork "JamesForWork (2 commits)") --- Tags apisymfonydocumentationswaggeropenapi ### 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.4k5.6M650](/packages/sylius-sylius)[nelmio/api-doc-bundle Generates documentation for your REST API from attributes 2.3k63.6M232](/packages/nelmio-api-doc-bundle)[shopware/platform The Shopware e-commerce core 3.3k1.5M3](/packages/shopware-platform)[sulu/sulu Core framework that implements the functionality of the Sulu content management system 1.3k1.3M152](/packages/sulu-sulu)[prestashop/prestashop PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers. 9.0k15.4k](/packages/prestashop-prestashop)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.2M386](/packages/shopware-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)