PHP code example of savionicodemos / laravel-auto-swagger

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

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

    

savionicodemos / laravel-auto-swagger example snippets

/**
 * @Request({
 *    "summary": "Title of the route",
 *    "description": "This is a longer description for the route which will be visible once the panel is expanded",
 *    "tags": ["Authentication","Users"]
 * })
 */

/**
 * You can also do this — the first line will be used as "summary"
 *
 * Anything after the first blank line counts as "description".
 *
 * @Request({
 *     "summary": "Title of the route",       // <- Overwrites the summary above if provided
 *     "description": "A short description",  // <- Overwrites description above if provided
 *     "tags": ["Authentication","Users"],      // <- Associates this operation with these tag sections
 *     "pathParams": [{                         // <- Overwrites auto-generated path parameter definitions
 *         "name": "user_id",
 *         "type": "string",
 *         "description": "User ID to fetch",
 *     }]
 * })
 */
public function someMethod(Request $request, string $reference) {}

/**
 * @Response({
 *     "code": 200,
 *     "description": "Return user model",
 *     "ref": "User"
 * })
 * @Response({
 *     "code": 400,
 *     "description": "Bad Request",
 *     "ref": "APIError[]"
 * })
 * @Response({
 *     "code": "302",
 *     "description": "Redirect"
 * })
 * @Response({
 *     "code": 500,
 *     "description": "Internal Server Error"
 * })
 */
public function someMethod(Request $request) {}

"ref": "User"              // <- Refers to the User schema
"ref": "APIError[]"        // <- Array of APIError schemas
"ref": "#/components/schemas/User"  // <- Full OpenAPI path
"ref": "P(User)"           // <- Schema builder (Laravel Pagination wrapping User)
"ref": "SP(User)"          // <- Schema builder (Laravel SimplePaginate wrapping User)

/**
 * @Response({"code": 200, "description": "PDF ticket.", "content_type": "application/pdf"})
 * @Response({"code": 401, "description": "Unauthorized."})
 */
public function download(): Response {}

/**
 * @Response({"code": 200, "description": "Export result.", "content_type": "application/pdf"})
 * @Response({"code": 200, "content_type": "text/csv"})
 * @Response({"code": 401, "description": "Unauthorized."})
 */
public function export(): Response {}

$rules = [
    'internal_token' => 'swagger_hidden',
    'internal_token.value' => 'string', // also hidden because parent is hidden
];

$rules = [
    'limit' => [
        $condition ? ' as 'swagger_

$rules = [
    'locale' => 'swagger_default:en_GB',
];

$rules = [
    'currency' => 'swagger_example:EUR',
];

$rules = [
    'limit' => 'swagger_description:Maximum number of items to return',
];

$rules = [
    'page' => 'swagger_default:1|swagger_min:1',         // docs only
    'page' => 'swagger_default:1|swagger_min:1:fail',    // docs + enforced
];

$rules = [
    'take' => 'swagger_default:10|swagger_min:1|swagger_max:50',       // docs only
    'take' => 'swagger_default:10|swagger_min:1|swagger_max:50:fail',  // docs + enforced
];

// app/Swagger/Schemas/Address.php
namespace App\Swagger\Schemas;

class Address
{
    public string  $street;
    public string  $city;
    public ?string $state;
    public string  $zip_code;
    public string  $country;
}

class FlightSchedule
{
    public \DateTime          $scheduled_at;   // → type: string, format: date-time
    public \DateTimeImmutable $completed_at;   // → type: string, format: date-time
    public ?\DateTimeInterface $cancelled_at;  // → type: string, format: date-time, nullable: true
    public ?string            $note;           // → type: string, nullable: true
}

class FlightSegment
{
    static string $origin_code = 'GRU';        // → example: "GRU"
    static int    $duration_minutes = 390;     // → example: 390
}

/**
 * @Schema({
 *     "{
    public string  $street;
    public string  $city;
    public ?string $state;
    public string  $zip_code;
    public string  $country;
}

class FlightSegment
{
    /**
     * @Property({"enum": ["economy", "business", "first"]})
     */
    static string $cabin_class = 'economy';

/**
 * @Property({"ref": "FlightDetails"})          // $ref to FlightDetails
 * @Property({"ref": "FlightSegment[]"})         // array of FlightSegments
 * @Property({"ref": "FlightDetails", "nullable": true, "description": "Optional detail"})
 */

/**
 * @Property({"raw": {"type": "string", "format": "uri"}})
 */
static string $booking_url = 'https://example.com';

// config/swagger.php (inside a page entry)
'schemas' => [
    app_path('Swagger/Schemas'),
    base_path('modules/Orders/Swagger/Schemas'),
    base_path('modules/Auth/Swagger/Schemas'),
],

// config/swagger.php (inside a page entry)
'tags' => [
    ['name' => 'Users',           'description' => 'Operations related to users'],
    ['name' => 'Authentication',  'description' => 'Login, logout, and token refresh'],
    ['name' => 'Flights',         'description' => 'Flight search and booking'],
],

shell
php artisan vendor:publish --provider "AutoSwagger\Docs\SwaggerServiceProvider"