mvaliolahi / sibdoc
PHP API Document Generator
Requires
- twig/twig: ^2.0
Requires (Dev)
- phpunit/phpunit: 6.2
This package is auto-updated.
Last update: 2024-10-09 20:58:50 UTC
README
Generate API Document Using Pure PHP.
Install
composer require mvaliolahi/sibdoc
1. Instantiate SibDoc.
To generate document for your awesome API create an instance of SibDoc:
$api = new SibDoc([ 'url' => 'http://127.0.0.1:8000', 'title' => 'Our Awesome API', 'description' => 'Generate API Document Using Lovely PHP.', ]);
- Tip: There is another optional argument called
'background_color => '#0099cc'
to specify Document background color.
2. Define Endpoints
$api->post('transactions/{id}', function (Request $request) { // Define Request. $request->title('Show transaction.'); $request->version("v1"); // Optional $request->parameters([ 'token' => 'required', 'transaction_id' => 'required', ]); // Define Response. $success = (new Response()) ->title('Success') ->code(200) ->body([ 'id' => 'numeric', 'status' => 'PAID | UNPAID', 'created_at' => 'timestamp', ]); // Assings Reaponses to the Request. $request->response($success); });
Tips:
-
Request can have more than one response, just define another Response object and assign it to
$request
. -
$request->response('Success', $success); is another way to assign response to request and define alias for response.
-
Request and Response they both have
description()
method, this method is optional. -
You can define Header for both Request and Response Objects using
headers()
method for example:$request->headers([])
.or define a general header for those using
$api->requestHeaders([])
or$api->responseHeaders([])
method.
Available methods:
- get
- post
- put
- patch
- delete
- head
- connect
- options
- trace
Define Group
$api->group('app', function(SibDoc $api) { $api->delete('posts/{id}', function (Request $request) { // Define request and response. }); });
Define Model
$api->model('user', [ 'id' => 'numeric', 'name' => 'string', 'family' => 'string', 'avatar' => 'url', ]);
Use model as part of response body
$api->get('users', function (Request $request) { $request->title('Get all users'); $request->version(1.2); $request->description('...'); $request->parameters(['token' => 'required']); $success = (new Response()) ->title('Success') ->description('...') ->code(200) ->body([ 'data' => [ $api->model('user') ] // when second argument is null it will act as getter. ]); $fail = (new Response()) ->title('Fail') ->description('...') ->code(404) ->body([ 'data' => [] ]); $request->response($success); $request->response($fail); });
3. Generate Html
By default SibDoc can generate a file called document.html
for you.
$api->saveTo('/home/meysam/');
Tips:
- first argument specify export path, after call
saveTo()
method with related parameters, it will generate a file calleddocument.html
in that path. - second argument refer to built-in Generator for create html file.
- you can define your custom generator to create you desire format, for example
markdown
or maybejson
file. i will demonstrate to you right below!
Create Custom Generator
first of all you need a regular class and you should extends it from DocumentGenerator
abstract class.
/** * Class FakeGenerator * @package Tests\Generators */ class FakeGenerator extends DocumentGenerator { /** * @param $path * @return mixed */ public function format($path) { return 'fake generator!'; } }
There are several method after extends your class that you can use to generate your custom format.
-
groups()
- gives you all defined groups. when group name is not string that's mean its not a group, means its a single endpoint.
-
endpoints()
- gives you an array contains all endpoints and group, each group can have several endpoint.
-
models()
-
backgroundColor()
- gives you the
background_color
value from what you pass as SibDoc instance argument.
- gives you the
it up to you how use them and how is your final format.
at the end you should pass your generator as argument to SibDoc:
$api = new SibDoc([ 'url' => 'http://127.0.0.1:8000', 'title' => 'SibDoc Document Generator', 'description' => 'Generate Api Document Using Pure PHP.', 'generator' => [ 'fake_generator' => FakeGenerator::class ], ]); // define you groups and endpoints $api->saveTo('/home/user/', 'fake_generator');