PHPackages                             wwwision/types-openapi - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. wwwision/types-openapi

ActiveLibrary[API Development](/categories/api)

wwwision/types-openapi
======================

Generator for OpenAPI schema files, see https://www.openapis.org/

2.2.1(5mo ago)17.0k1MITPHPPHP >=8.3CI passing

Since Apr 3Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/bwaidelich/types-openapi)[ Packagist](https://packagist.org/packages/wwwision/types-openapi)[ GitHub Sponsors](https://github.com/sponsors/bwaidelich)[ Fund](https://www.paypal.me/bwaidelich)[ RSS](/packages/wwwision-types-openapi/feed)WikiDiscussions main Synced yesterday

READMEChangelog (6)Dependencies (11)Versions (8)Used By (0)

The easiest way to generate type-safe APIs with PHP...
======================================================

[](#the-easiest-way-to-generate-type-safe-apis-with-php)

...possibly... ;)

Integration for the [wwwision/types](https://github.com/bwaidelich/types) package that allows for generation of [OpenAPI](https://www.openapis.org/) schemas and APIs from PHP code

Usage
-----

[](#usage)

This package can be installed via [composer](https://getcomposer.org):

```
composer require wwwision/types-openapi
```

### Simple Example

[](#simple-example)

This is all that is required to generate an OpenAPI schema for a simple HTTP endpoint:

```
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 = 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();
```

### Parameters

[](#parameters)

Arguments of the endpoint methods are automatically mapped to OpenAPI parameters. All OpenAPI parameter types are supported (`query`, `path`, `header`, `cookie`).

#### Query parameters

[](#query-parameters)

By default, the parameter type is `query`:

```
final class SomeApi {

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

will accept requests like

```
GET /?someParam=foo HTTP/1.1
```

and

```
GET /?someParam=foo&someOptionalParam=bar HTTP/1.1
```

and will map the values to the corresponding method arguments.

#### Path parameters

[](#path-parameters)

Operations can also make use of [Path Templating](https://swagger.io/specification/#path-templating) in order to map method arguments from the query path:

```
final class SomeApi {

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

Path params cannot be optional and must be defined in the path template.

#### Header parameters

[](#header-parameters)

To define a header parameter, the `#[Parameter]` attribute can be used:

```
final class SomeApi {

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

#### Cookie parameters

[](#cookie-parameters)

Likewise, to define a cookie parameter, the `#[Parameter]` attribute can be used:

```
final class SomeApi {

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

#### Complex types

[](#complex-types)

Complex parameter types are supported as well as long as they follow the [wwwision/types best practices](https://github.com/bwaidelich/types?tab=readme-ov-file#best-practices):

```
#[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;
    }
}
```

This will validate and map the parameter and fail if it does not satisfy the constraints:

```
{
  "type": "https://www.rfc-editor.org/rfc/rfc9110#name-400-bad-request",
  "title": "Bad Request",
  "issues": [
    {
      "code": "too_small",
      "message": "String must contain at least 3 character(s)",
      "path": [
        "query.username"
      ],
      "type": "string",
      "minimum": 3,
      "inclusive": true,
      "exact": false
    }
  ]
}
```

#### Example

[](#example)

The following example makes use of all parameter types:

```
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());
    }
}
```

This will lead to an OpenAPI definition like this:

```
{
  // ...
  "paths": {
    "/{paramFromPath}": {
      "get": {
        "operationId": "someEndpoint",
        "parameters": [
          {
            "name": "paramFromPath",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Foo",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SomeCookie",
            "in": "cookie",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "paramFromQuery",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        // ...
      }
    }
  }
}
```

And an HTTP request like:

```
GET /valueFromPath?paramFromQuery=valueFromQuery HTTP/1.1
Host: localhost:8000
X-Foo: valueFromHeader
Cookie: SomeCookie=valueFromCookie
```

...will result in the following response:

```
["valueFromPath","valueFromHeader","valueFromCookie","valueFromQuery"]
```

### Security

[](#security)

To implement custom authentication schemes, you can implement the `AuthenticationContextProvider` interface and return an instance of your custom `AuthenticationContext` class:

```
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 requirement
        return new CustomAuthContext(authenticatedUserId: 'john.doe');
    }
}
```

The `AuthenticationContext` is passed to the endpoint method as an additional argument, if the `security` option of the `Operation` attribute is set. The `RequestHandler` will automatically call the `getAuthenticationContext()` method of your provider and pass the result to the endpoint method. Security schemes can be defined using the `#[OpenApi]` attribute:

```
// ...

#[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();
    }
}
```

### More Examples

[](#more-examples)

**More complex example**```
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
 */
#[Description('A set of users')]
#[ListBased(itemClassName: User::class)]
final class Users implements IteratorAggregate
{
    /**
     * @param array $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' => 'contact@example.com'], 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 =  new User(Username::fromString('john.doe'), EmailAddress::fromString('john.doe@example.com')),
            'jane.doe' => new User(Username::fromString('jane.doe'), EmailAddress::fromString('jane.doe@example.com')),
        ];
    }

    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 requirement
        return new CustomAuthContext(authenticatedUserId: 'john.doe');
    }
}

$api = new SomeApi(new FakeUserRepository());
$httpFactory = new HttpFactory();
$requestHandler = new RequestHandler($api, $httpFactory, $httpFactory, authenticationContextProvider: new AuthContextProvider());

$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();
```

Contribution
------------

[](#contribution)

Contributions in the form of [issues](https://github.com/bwaidelich/types-openapi/issues) or [pull requests](https://github.com/bwaidelich/types-openapi/pulls) are highly appreciated

License
-------

[](#license)

See [LICENSE](./LICENSE)

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance70

Regular maintenance activity

Popularity26

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 94.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~57 days

Recently: every ~70 days

Total

6

Last Release

169d ago

Major Versions

1.0.0 → 2.0.02025-04-10

PHP version history (2 changes)1.0.0PHP >=8.1

2.0.0PHP >=8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/307571?v=4)[Bastian Waidelich](/maintainers/bwaidelich)[@bwaidelich](https://github.com/bwaidelich)

---

Top Contributors

[![bwaidelich](https://avatars.githubusercontent.com/u/307571?v=4)](https://github.com/bwaidelich "bwaidelich (17 commits)")[![reflexxion](https://avatars.githubusercontent.com/u/3419968?v=4)](https://github.com/reflexxion "reflexxion (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/wwwision-types-openapi/health.svg)

```
[![Health](https://phpackages.com/badges/wwwision-types-openapi/health.svg)](https://phpackages.com/packages/wwwision-types-openapi)
```

###  Alternatives

[cakephp/cakephp

The CakePHP framework

8.9k19.5M1.8k](/packages/cakephp-cakephp)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[thecodingmachine/graphqlite

Write your GraphQL queries in simple to write controllers (using webonyx/graphql-php).

5733.3M47](/packages/thecodingmachine-graphqlite)[typo3/cms-core

TYPO3 CMS Core

3713.2M5.1k](/packages/typo3-cms-core)[mcp/sdk

Model Context Protocol SDK for Client and Server applications in PHP

1.5k1.5M88](/packages/mcp-sdk)[mezzio/mezzio

PSR-15 Middleware Microframework

3923.8M125](/packages/mezzio-mezzio)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)