Symfony 3.3中NelmioApiDoc v3能否实现多视图端点分URL展示？

Absolutely! You can replicate the multiple views functionality (hiding specific endpoints and displaying them on separate URLs) from NelmioApiDoc v2 in NelmioApiDoc v3 (Swagger) with Symfony 3.3. The approach differs a bit from v2, but the core capability is fully supported. Here's how to set it up:

1. Configure Multiple Documentation Sets #

First, define your separate "views" (called documentation entries) in your config.yml file. Each entry gets a unique id, custom metadata, and rules to include/exclude endpoints.

Example: Path-Based Filtering #

This setup creates two views: one for public endpoints, one for admin-only endpoints, using path patterns:

nelmio_api_doc:
    documentation:
        -
            id: public
            info:
                title: Public API Documentation
                version: 1.0.0
            paths:
                # Include only paths under /api/public
                /api/public/*: ~
        -
            id: admin
            info:
                title: Admin API Documentation
                version: 1.0.0
            paths:
                # Include only paths under /api/admin
                /api/admin/*: ~

Example: Exclusion-Based Filtering #

If you prefer to exclude specific routes instead, use the exclude option:

nelmio_api_doc:
    documentation:
        -
            id: public
            info:
                title: Public API Documentation
                version: 1.0.0
            exclude:
                # Exclude all admin routes
                - { path: ^/api/admin }
        -
            id: admin
            info:
                title: Admin API Documentation
                version: 1.0.0
            exclude:
                # Exclude all public routes
                - { path: ^/api/public }

2. Map Documentation Sets to Unique URLs #

Next, add routes in your routing.yml file to expose each documentation set on a distinct URL. Use the built-in Swagger controller and specify the documentation parameter to link to your view ID:

# Public API docs URL
app_api_doc_public:
    path: /api/docs/public
    methods: GET
    defaults:
        _controller: nelmio_api_doc.controller.swagger
        documentation: public

# Admin API docs URL
app_api_doc_admin:
    path: /api/docs/admin
    methods: GET
    defaults:
        _controller: nelmio_api_doc.controller.swagger
        documentation: admin

3. Fine-Grained Endpoint Control (Optional) #

If you need to mark individual controller methods as belonging to a specific view (instead of relying on path rules), use the @ApiDoc annotation with the documentation attribute:

<?php

namespace AppBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Nelmio\ApiDocBundle\Annotation\ApiDoc;

class AdminController extends Controller
{
    /**
     * @ApiDoc(
     *     documentation="admin", // Links this endpoint to the 'admin' view
     *     description="Fetch all user accounts (admin only)"
     * )
     */
    public function listUsersAction()
    {
        // Your logic here
    }
}

Important Notes for Symfony 3.3 #

• Stick to a compatible version of NelmioApiDocBundle: For Symfony 3.3, use NelmioApiDocBundle 3.x versions up to 3.6 (later 3.x versions may drop Symfony 3.3 support).
• Clear your Symfony cache after making configuration changes to ensure the new views load correctly.

That's it! Now you can visit /api/docs/public to see your public endpoints and /api/docs/admin for admin-only ones, just like you did with v2's multiple views.

内容的提问来源于stack exchange，提问作者breq