PHP download

PHP code example of wwwision / types-openapi

1. Go to this page and download the library: Download wwwision/types-openapi library. Choose the download type require.

2. Extract the ZIP file and open the index.php.

3. Add this code to the index.php.

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

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

wwwision / types-openapi example snippets


final class SomeApi {

    #[Operation(path: '/', method: 'GET')]
    public function someEndpoint(): string {
        return '{"success":true}';
    }
}

$openApiObject = (new OpenApiGenerator())->generate(SomeApi::class);

assert($openApiObject instanceof OpenApiObject);
$expectedSchema = <<<JSON
{"openapi":"3.0.3","info":{"title":"","version":"0.0.0"},"paths":{"\/":{"get":{"operationId":"someEndpoint","responses":{"200":{"description":"Default","content":{"application\/json":{"schema":{"type":"string"}}}}}}}}}
JSON;
assert(json_encode($openApiObject) === $expectedSchema);


// ... 

$api = new SomeApi();
$httpFactory = new HttpFactory();
$requestHandler = new RequestHandler($api, $httpFactory, $httpFactory);

$request = ServerRequest::fromGlobals();
try {
    $response = $requestHandler($request);
} catch (RequestException $e) {
    $response = $httpFactory->createResponse($e::getStatusCode(), $e::getReasonPhrase());
    $response->getBody()->write($e->getMessage());
}
http_response_code($response->getStatusCode());
foreach ($response->getHeaders() as $k => $values) {
    foreach ($values as $v) {
        header(sprintf('%s: %s', $k, $v), false);
    }
}
echo $response->getBody();


final class SomeApi {

    #[Operation(path: '/', method: 'GET')]
    public function someEndpoint(string $someParam, string|null $someOptionalParam = null): string {
        return $someParam;
    }
}


final class SomeApi {

    #[Operation(path: '/static/{param1}/{param2}', method: 'GET')]
    public function someEndpoint(string $param1, string $param2): string {
        // ...
    }
}


final class SomeApi {

    #[Operation(path: '/', method: 'GET')]
    public function someEndpoint(#[Parameter(in: ParameterLocation::header, name: "X-HeaderName")] string $paramFromHeader): string {
        // ...
    }
}


final class SomeApi {

    #[Operation(path: '/', method: 'GET')]
    public function someEndpoint(#[Parameter(in: ParameterLocation::cookie, name: "CookieName")] string $paramFromCookie): string {
        // ...
    }
}


#[StringBased(minLength: 3)]
final readonly class Username {
    private function __construct(
        public string $value,
    ) {}
}

final class SomeApi {

    #[Operation(path: '/', method: 'GET')]
    public function someEndpoint(Username $username): string {
        return $username->value;
    }
}


final class SomeApi {

    #[Operation(path: '/{paramFromPath}', method: 'GET')]
    public function someEndpoint(
        string $paramFromPath,
        #[Parameter(in: ParameterLocation::header, name: "X-Foo")]
        string $paramFromHeader,
        #[Parameter(in: ParameterLocation::cookie, name: "SomeCookie")]
        string $paramFromCookie,
        string $paramFromQuery,
    ): string {
        return json_encode(func_get_args());
    }
}


final class CustomAuthContext implements AuthenticationContext {
    public function __construct(
        public readonly string|null $authenticatedUserId,
    ) {
    }
}

final class AuthContextProvider implements AuthenticationContextProvider {
    public function getAuthenticationContext(ServerRequestInterface $request, SecurityRequirementObject $securityRequirement): CustomAuthContext|null {
        // TODO: evaluate the request and security


// ...

#[OpenApi(
    // ...
    securitySchemes: [
        'someSchema' => [
            'type' => 'http',
            'scheme' => 'bearer',
        ],
    ],
)]
final class SomeApi {

    #[Operation(path: '/', method: 'POST', security: 'someSchema')]
    public function securedEndpoint(CustomAuthContext $authContext): CreatedResponse
    {
        if ($authContext->authenticatedUserId !== 'john.doe') {
            return new UnauthorizedResponse();
        }
        // do something
        return new CreatedResponse();
    }
}


final class CustomAuthContext implements AuthenticationContext {
    public function __construct(
        public readonly string|null $authenticatedUserId,
    ) {
    }
}

#[Description('Unique handle for a user in the API')]
#[StringBased(minLength: 1, maxLength: 200)]
final class Username {
    private function __construct(
        public readonly string $value,
    ) {
    }

    public static function fromString(string $value): self {
        return instantiate(self::class, $value);
    }
}

#[Description('Email address of a user')]
#[StringBased(format: StringTypeFormat::email)]
final class EmailAddress {
    private function __construct(
        public readonly string $value,
    ) {
    }

    public static function fromString(string $value): self {
        return instantiate(self::class, $value);
    }
}

final class User {

    public function __construct(
        public readonly Username $username,
        public readonly EmailAddress $emailAddress,
    ) {
    }
}

/**
 * @implements IteratorAggregate<User>
 */
#[Description('A set of users')]
#[ListBased(itemClassName: User::class)]
final class Users implements IteratorAggregate
{
    /**
     * @param array<User> $users
     */
    private function __construct(private readonly array $users) {
    }

    public static function fromArray(array $users): self {
        return instantiate(self::class, $users);
    }

    public function getIterator(): Traversable {
        yield from $this->users;
    }
}

final class AddUser {
    public function __construct(
        public readonly Username $username,
        public readonly EmailAddress $emailAddress,
    ) {
    }
}

interface UserRepository {
    public function findAll(): Users;
    public function findByUsername(Username $username): User|null;
    public function add(User $user): void;
}

#[OpenApi(apiTitle: 'Some API', apiVersion: '1.2.3', openApiVersion: '3.0.3', contact: ['name' => 'Contact Name', 'url' => 'https://contact-url.example.com', 'email' => '[email protected]'], license: ['name' => 'License name', 'id' => 'licenseId', 'url' => 'https://license.example.com'], securitySchemes: ['basicAuth' => ['type' => 'http', 'scheme' => 'basic', 'description' => 'Basic authentication']])]
#[Description('Some API description')]
final class SomeApi
{

    public function __construct(
        private readonly UserRepository $userRepository,
    ) {
    }

    #[Operation(path: '/users', method: 'GET', summary: 'Get Users')]
    #[Description('Retrieves all users from the repository')]
    public function users(): Users
    {
        return $this->userRepository->findAll();
    }

    #[Operation(path: '/users/{username}', method: 'GET', summary: 'Get a single user by its username')]
    #[Description('Retrieves a single user or returns a 404 response if not found')]
    public function userByUsername(Username $username): User|NotFoundResponse
    {
        return $this->userRepository->findByUsername($username) ?: new NotFoundResponse();
    }

    #[Operation(path: '/users', method: 'POST', summary: 'Add a new user', security: 'basicAuth')]
    #[Description('Saves a new user to the repository')]
    public function addUser(AddUser $command, CustomAuthContext $authContext): CreatedResponse|UnauthorizedResponse
    {
        if ($authContext->authenticatedUserId !== 'john.doe') {
            return new UnauthorizedResponse();
        }
        $this->userRepository->add(new User($command->username, $command->emailAddress));
        return new CreatedResponse();
    }
}

$generator = new OpenApiGenerator();
$openApiObject = $generator->generate(SomeApi::class, OpenApiGeneratorOptions::create());
assert($openApiObject instanceof OpenApiObject);
$expectedSchema = <<<'JSON'
{"openapi":"3.0.3","info":{"title":"Some API","version":"1.2.3","description":"Some API description","contact":{"name":"Contact Name","url":"https:\/\/contact-url.example.com","email":"[email protected]"},"license":{"name":"License name","url":"https:\/\/license.example.com"}},"paths":{"\/users":{"get":{"summary":"Get Users","description":"Retrieves all users from the repository","operationId":"users","responses":{"200":{"description":"Default","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Users"}}}}}},"post":{"summary":"Add a new user","description":"Saves a new user to the repository","operationId":"addUser","requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AddUser"}}},"


// ...
final class FakeUserRepository implements UserRepository {

    /**
     * @var array<string, User>
     */
    private array $usersByUsername;

    public function __construct()
    {
        $this->usersByUsername = [
            'john.doe' => new User(Username::fromString('john.doe'), EmailAddress::fromString('[email protected]')),
            'jane.doe' => new User(Username::fromString('jane.doe'), EmailAddress::fromString('[email protected]')),
        ];
    }

    public function findAll(): Users {
        return Users::fromArray(array_values($this->usersByUsername));
    }

    public function findByUsername(Username $username): User|null
    {
        return $this->usersByUsername[$username->value] ?? null;
    }

    public function add(User $user): void
    {
        $this->usersByUsername[$user->username->value] = $user;
    }
}

final class AuthContextProvider implements AuthenticationContextProvider {
    public function getAuthenticationContext(ServerRequestInterface $request, SecurityRequirementObject $securityRequirement): CustomAuthContext|null {
        // TODO: evaluate the request and security