ApiDoc is a plugin for documenting the API.

Installation:

1st option: artisan plugin:install Gumennikov2002.ApiDoc

2nd option: Via marketplace

Document properties:

• title (string, required)
• tags (string[]) / tag (string)
• url (string, required)
• method (string, required)
• params (array)
• responses (array)

see Gumennikov2002\ApiDoc\Classes\Constructors\DocumentConstructor

Parameter properties:

• title (string, required)
• description (string)
• in (string, required)
• required (boolean, required)
• example (mixed, required)

see Gumennikov2002\ApiDoc\Classes\Constructors\ParameterConstructor

Response properties:

• status_code (int, required)
• response (array, required)

see Gumennikov2002\ApiDoc\Classes\Constructors\ResponseConstructor

Usage example (via array):

In your plugin in the Plugin class, in the boot method, add the Gumennikov2002\ApiDoc\Controllers\Docs controller, assign its public docs property an array containing arrays with instructions.

Code example:

public function boot(): void
    {
        \Gumennikov2002\ApiDoc\Controllers\Docs::extend(function (\Backend\Classes\Controller $controller) {
            $controller->docs = [
                [
                    'title' => 'Get posts',
                    'tag' => 'Pосты',
                    'url' => 'https://example.com/api/v1/posts',
                    'method' => 'get',
                    'responses' => [
                        [
                            'status_code' => 200,
                            'response' => [
                                'data' => [
                                    [
                                        'id' => 1,
                                        'title' => 'First blog post!',
                                        'description' => 'No description provided...'
                                    ],
                                    [
                                        'id' => 2,
                                        'title' => 'Second blog post!',
                                        'description' => null
                                    ]
                                ]
                            ]
                        ]
                    ]
                ],
                [
                    'title' => 'Get post by ID',
                    'tag' => 'Posts',
                    'url' => 'https://example.com/api/v1/posts/{id}',
                    'method' => 'get',
                    'params' => [
                        [
                            'title' => 'id',
                            'description' => 'Post ID',
                            'in' => 'path',
                            'required' => true,
                            'example' => 1
                        ]
                    ],
                    'responses' => [
                        [
                            'status_code' => 200,
                            'response' => [
                                'data' => [
                                    'id' => 1,
                                    'title' => 'First blog post!',
                                    'description' => 'No description provided...'
                                ],
                            ]
                        ]
                    ]
                ]
            ];
        });
    }

Usage example (via constructors):

Code example:

public function boot(): void
{
    \Gumennikov2002\ApiDoc\Controllers\Docs::extend(function (\Backend\Classes\Controller $controller) {
        # Common documents pool
        $documentPool = new Pool;

        # DOCUMENT 1: All posts
        $allPostsDocument = (new DocumentConstructor)
            ->setTitle('Get all posts')
            ->setTags(['Posts'])
            ->setUrl('https://example.com/api/v1/posts')
            ->setMethod('get');
        $allPostsResponsesPool = new Pool;
        $allPostsOkResponse = (new ResponseConstructor)->setResponse(
            [
                'data' => [
                    [
                        'id' => 1,
                        'title' => 'First blog post!',
                        'description' => 'No description provided...'
                    ],
                    [
                        'id' => 2,
                        'title' => 'Second blog post!',
                        'description' => null
                    ]
                ]
            ]
        );
        $allPostsResponsesPool->add($allPostsOkResponse);
        $allPostsDocument->setResponsesPool($allPostsResponsesPool);

        # DOCUMENT 2: Post by id
        $postByIdDocument = (new DocumentConstructor)
            ->setTitle('Get posts by ID')
            ->setTag('Posts')
            ->setUrl('https://example.com/api/v1/posts/{id}')
            ->setMethod('get');
        $postByIdDocumentParamsPool = new Pool;
        $postByIdDocumentParamId = (new ParameterConstructor)->setTitle('id')
            ->setDescription('Post ID')
            ->setRequired()
            ->setIn('path')
            ->setExample(1);
        $postByIdDocumentParamsPool->add($postByIdDocumentParamId);
        $postByIdDocumentResponsesPool = new Pool;
        $postByIdDocumentResponseOk = (new ResponseConstructor)->setResponse([
            'data' => [
                'id' => 1,
                'title' => 'First blog post!',
                'description' => 'No description provided...'
            ],
        ]);
        $postByIdDocumentResponsesPool->add($postByIdDocumentResponseOk);
        $postByIdDocument->setParametersPool($postByIdDocumentParamsPool)
            ->setResponsesPool($postByIdDocumentResponsesPool);

        $documentPool->addMultiple(
            $allPostsDocument,
            $postByIdDocument
        );

        $controller->docs = $documentPool->get();
    });
}