ApiDoc is a plugin for documenting the API.
Turns a regular PHP array into a documentation page
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(); }); }
-
This plugin has not been reviewed yet.
-
1.0.4 |
Plugin assets path Nov 20, 2023 |
---|---|
1.0.3 |
Show/Hide card body Nov 13, 2023 |
1.0.2 |
Constructors Nov 09, 2023 |
1.0.1 |
Api documentation Nov 03, 2023 |