PHP code example of andrii-hrechyn / auto-documentation

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

andrii-hrechyn / auto-documentation example snippets

Route::post('users.store')
    ->summary('Create user')
    ->fromFormRequest()                          // request body from validation rules, adds a 422 preset
    ->jsonResponse(UserSchema::make(), 201);

// docs/info.php
return AutoDoc::make()
    ->info(Info::make('My API', '1.0.0'))
    ->servers([Server::make('https://api.example.com')])
    ->security(SanctumAuth::make())
    ->defaultSecurity(SanctumAuth::make());   // applied to every ->secure() operation

// docs/Paths/users.php
return [
    Route::get('users.show')
        ->summary('Get user')
        ->jsonResponse(UserSchema::make()),

    Route::post('users.store')
        ->summary('Create user')
        ->fromFormRequest()
        ->jsonResponse(UserSchema::make(), 201),
];

return [
    Path::make('/orders/{order}')
        ->method(
            Method::get()
                ->summary('Get order')
                ->tag('orders')
                ->group('Shop')                      // Redoc x-tagGroups
                ->parameter(
                    Parameter::make('order', ParameterIn::PATH)
                        ->

ObjectSchema::make([
    StringProperty::make('status')->enum(OrderStatus::class)->e('note')->nullable(),
])->additionalProperties(false);

CompositeSchema::oneOf([CardPayment::make(), CashPayment::make()])
    ->discriminator('type');

->jsonResponse(Schema::fromExample([
    'id' => 1, 'name' => 'Ann', 'deleted_at' => null,
]))

// e.g. in a service provider
ValidationRuleParser::extend(PhoneNumber::class,
    fn () => StringSchema::make()->pattern('^\+\d{10,15}$'));

ValidationRuleParser::extend('currency',
    fn (string $rule) => StringSchema::make()->enum(explode(',', Str::after($rule, ':'))));

use AutoDocumentation\Testing\AssertsApiDoc;

$response = $this->getJson('/api/users/1');

$this->assertResponseMatchesApiDoc($response, '/api/users/{user}', 'get');

docs
├── Components
│   ├── Parameters/ExampleParameter.php
│   └── Schemas/ExampleSchema.php
├── Paths
│   └── testPaths.php
└── info.php

bash
php artisan auto-doc:generate   # writes storage/app/auto-docs/documentation.yaml

bash
php artisan vendor:publish --tag=auto-documentation

bash
php artisan auto-doc:lint          # exit code 1 on errors
php artisan auto-doc:lint --strict # warnings fail too