Alternative: #49856. Please close this one once it is ready

See https://github.com/symfony/symfony/pull/49785#issuecomment-1487144869

I want this as well. I think targeting 6.4 is fine, we'll need to adapt the way commands are tracked to take the upcoming Console changes into account anyway.

As a symfony/* component

Fine by me as long as you maintain it :)

I think we need this to work out-of-the-box with a properly maintained reference implementation anyway :)

ping @Spomky FYI

This reverts commit c37540613922ec64cc8ff0e0a4ad21bd6b4ddb74, reversing changes made to 497e9666de46420299e2732cf2e97451b2792bf0.

| Q | A | ------------- | --- | Branch? | 6.3 | Bug fix? | no | New feature? | yes | Deprecations? | no | Tickets | - | License | MIT | Doc PR | -

The dev dependency added in #49789 looks problematic: https://github.com/bjeavons/zxcvbn-php has no commit in 2 years, ignored vulnerability reports + unmerged php compatibility fixes. Worse, the JS project it's based on didn't make any change in 6 years, has ignored security reports as well and seems to be officially abandoned (https://github.com/dropbox/zxcvbn/issues/290, https://github.com/dropbox/zxcvbn/issues/295).

I propose to revert this change for now, then revisit the topic as soon as possible. Also some core members argued that this feature could be better handled on the frontend i.e. rewritten as a UX component or a cookbook example. Either way, if we want to do re-add this, we would need to fork and update the abandoned package. And if it's frontend, we need to find a maintained alternative.

Indeed, Symfony inlines the Response::HTTP_* internally for this reason. Either way, making it consistent across the board would make sense IMO

| Q | A | ------------- | --- | Branch? | 6.3 | Bug fix? | no | New feature? | yes | Deprecations? | no | Tickets | - | License | MIT | Doc PR | https://github.com/symfony/symfony-docs/issues/17987

This PR proposes the introduction of a new OpenApi component to the Symfony ecosystem. The component aims at providing a user-friendly, object-oriented API to build OpenAPI specifications using PHP.

This component's proposal comes from difficulties we (at Selency) encountered while trying to implement a high-quality documentation using alternatives (like NelmioApiDocBundle or swagger-php):

1. AFAIK existing OpenApi packages in PHP are focused on the code: it is usually difficult to create a documentation independant from the structure of the application. They work using attributes and focus on describing the code, not the usage of the API. This leads to resulting documentations being difficult to use by consumers.
2. In addition, because such packages are so tied to the code, it is difficult to maintain multiple documentations at the same time: this means it's difficult to create different documentations for different API versions in the same codebase.

To address these issues, our proposal is instead to rely on PHP and its capabilities: in the same way we can now define services in PHP with autocompleted method names and linting, this component proposes the ability to describe an OpenApi documentation in PHP, and then dump it as JSON or YAML for usage in other tools. All features of OpenApi v3.1 are supported.

Simple usage example

use Symfony\Component\OpenApi\Documentation\AbstractDocumentation;

class Documentation extends AbstractDocumentation
{
    public function getIdentifier(): string
    {
        return 'myapi';
    }

    public function getVersion(): string
    {
        return '1.3.4';
    }

    public function configure(DocumentationConfigurator $doc): void
    {
        $doc->info($this->openApi->info()
            ->title('Monolith API')
            ->description(file_get_contents(__DIR__.'/Resources/info_description.md'))
            ->contact(name: 'API support', url: 'https://symfony.com', email: 'contact@symfony.com')
            ->specificationExtension('x-logo', [
                'url' => 'https://symfony.com/logos/symfony_black_02.png',
                'altText' => 'Symfony logo',
            ])
            ->license('MIT')
        );

        $doc->externalDocs(url: 'https://github.com/symfony/openapi', description: 'OpenApi component');

        $doc->server($this->openApi->server('https://api.symfony.local')->description('Local'))
            ->server($this->openApi->server('https://api.symfony-staging.com')->description('Staging'))
            ->server($this->openApi->server('https://api.symfony.com')->description('Prod'));

        $doc->securityRequirement(self::REF_SECURITY_USER_JWT);

        $doc->path('/health', $this->openApi->pathItem()
            ->get($this->openApi->operation()
                ->tag('Health')
                ->operationId('app.health.check')
                ->summary('Health check')
                ->description('Check the API is up and available.')
                ->securityRequirement(null)
                ->responses($this->openApi->responses()
                    ->response('200', $this->openApi->response()
                        ->description('When the API is up and available.')
                        ->content('application/json', $this->openApi->schema()
                            ->property('name', $this->openApi->schema()->type('string')->description('Name for this API')->example('Selency API'))
                            ->property('env', $this->openApi->schema()->type('string')->description('Current environment of this instance of the API')->example('prod'))
                        )
                    )
                    ->response('500', $this->openApi->response()->description('When the API is unavailable due to a backend problem.'))
                )
            )
        );

        // ...
    }
}

// Build a read-only model representing the documentation
$compiler = new DocumentationCompiler();
$openApiDefinition = $compiler->compile($doc);

// Compile it as YAML or JSON for usage in other tools
$openApiYaml = (new Dumper\YamlDumper())->dump($openApiDefinition);
$openApiJson = (new Dumper\JsonDumper())->dump($openApiDefinition);

You can find more advanced usages in the README.

Note: without having concerted our efforts, I recently realized that this component works very nicely with https://github.com/symfony/symfony/pull/49138 as well, by giving the possibility to put the documentation in payloads.

If this component is approved, I plan to do the FrameworkBundle integration right after to automate several aspects of its usage: self-describing schemas/query params loading, openapi directory creation in the project, ...

I'm closing this PR given the code has been released under the Selency organization and API p Platform extracted their OpenAPI component meanwhile (https://github.com/api-platform/openapi). Thanks everyone for the work and discussion.

Oh sure, let me reach out to you on slack probably next week. I think this can be closed meanwhile so that nobody picks it, the work has started so there's some material already :)

rebase needed

Changing a subscriber into a listener does not change the final behavior, so if there is no direct reference to the deprecated classes then therés nothing to do and this can be closed.