注释如何在 NelmioApiDocBundle 上工作

Question

在我的 symfony 项目中，我按照 NelmioApiDocBundle 的文档来记录我的 api。我可以访问 http://localhost/api/doc 上的端点，并且添加了一个自定义端点来测试返回 Json 200 响应的 http://localhost/healthcheck。 我的问题是，当我尝试添加有关端点的注释和信息时，它不起作用。文档上没有显示任何内容，我是否错过了什么？

这是我的 nelmio_api_doc.yaml

    documentation:
        info:
            title: My App
            description: This is an awesome app!
            version: 1.0.0
    areas: # to filter documented areas
        path_patterns:
            - ^/api(?!/doc$) # Accepts routes under /api except /api/doc
            - ^/healthcheck # Accepts routes under /api except /api/doc

这是我的控制器

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Annotation\Route;
use Nelmio\ApiDocBundle\Annotation\Model;
use Nelmio\ApiDocBundle\Annotation\Security;
use OpenApi\Annotations as OA;

class HealthcheckController extends AbstractController
{
    #[Route('/healthcheck', name: 'healthcheck', methods: 'GET')]
    /**
     * 
     * @OA\Get(
     *     path="/healthcheck",
     *     summary="Check the health of the application",
     *     description="This endpoint is used to check the health of the application.",
     *     @OA\Response(
     *         response=200,
     *         description="Returns OK if the application is healthy",
     *         @OA\JsonContent(
     *             type="object",
     *             @OA\Property(property="result", type="string", example="OK")
     *         )
     *     ),
     *     security={}
     * )
     * 
     */
    public function index(): JsonResponse
    {
        return new JsonResponse(["result" => "OK"], 200);
    }
}

Answer 1

这是我的 symfony 6 应用程序健康控制器代码。是的，在你进行练习之前，获得正确的属性是很烦人的：

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Api\Dto\InfoDto;
use Nelmio\ApiDocBundle\Annotation\Model;
use OpenApi\Attributes as OA;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class HealthController extends AbstractController
{
    #[
        OA\Get(
            operationId: 'Readiness',
            description: 'Readiness',
            summary: 'checks readiness of application',
            tags: ['health readiness'],
            responses: [
                new OA\Response(
                    response: 200,
                    description: 'Success',
                    content: new OA\JsonContent(ref: new Model(type: InfoDto::class), type: 'object')
                ),
                new OA\Response(response: 500, description: 'Internal Server Error'),
            ]
        ),
        Route(path: '/health/readiness', name: 'readiness', methods: ['GET'])
    ]
    public function readiness(): JsonResponse
    {
        return new JsonResponse(null, Response::HTTP_NO_CONTENT);
    }

    #[
        OA\Get(
            operationId: 'health',
            description: 'health',
            summary: 'checks health of application',
            tags: ['health'],
            responses: [
                new OA\Response(
                    response: 200,
                    description: 'Success',
                    content: new OA\JsonContent(ref: new Model(type: InfoDto::class), type: 'object')
                ),
                new OA\Response(response: 500, description: 'Internal Server Error'),
            ]
        ),
        Route(path: '/health', name: 'health', methods: ['GET'])
    ]
    public function health(): JsonResponse
    {
        return new JsonResponse(null, Response::HTTP_NO_CONTENT);
    }
}