README

使用 PHP 注释生成 API 文档的简单库。

如何使用

将 PHP 文档注释添加到您的控制器类中。

<?php

namespace App\Controller;

...
use IcyMat\ApiDoc\Annotation\ApiMethod;
use IcyMat\ApiDoc\Annotation\ApiRoute;
use IcyMat\ApiDoc\Annotation\ApiDescription;
use IcyMat\ApiDoc\Annotation\ApiParams;
use IcyMat\ApiDoc\Annotation\ApiResponse;

class NotesController extends Controller
{
    /**
     * @ApiMethod(method="PUT")
     * @ApiRoute(name="/notes/{id}/save")
     * @ApiParams(name="title", type="string", nullable=false, required=true, description="New note title")
     * @ApiParams(name="content", type="string", nullable=true, required=false, description="New note text content")
     * @ApiParams(name="handwriting", type="string", nullable=true, required=false, description="New note handwriting content encoded using base64 algorithm")
     * @ApiParams(name="background", type="string", nullable=true, required=false, description="New note hex code of background color")
     * @ApiParams(name="pattern", type="string", nullable=true, required=false, description="New note pattern name; available: lines / checkered")
     * @ApiDescription(section="Notes", description="Save existing note changes")
     *
     * @ApiResponse(description="Success response", response="{'status': 'success'}")
     * @ApiResponse(description="Example error response", response="{'status': 'error', 'code': 403, 'message': 'Forbidden'}")
     */
    public function noteSave(Note $note, NotesManager $notesManager, Request $request)
    {
        if ($note->getUser() != $this->getUser()) {
            return new JsonResponse(['status' => 'error', 'code' => 'notes_01', 'message' => 'Access denied'], 403);
        }

        $notesManager->saveNoteFromRequest($note, $request);

        return new JsonResponse(['status' => 'success']);
    }
}

要生成文档，应使用以下命令

php vendor/bin/api_docs_generator sourceDirectory destinationDirectory

执行此操作后，您可以在 destinationDirectory/documentation.html 中找到所有已记录的方法。