Global unified configuration suggestions

[caixingyue]

I have used the Java springdoc-openapi-starter-webmvc-ui package. In the global configuration, I think it is better than the existing PHP swagger package configuration scheme.

This is a solution that I conceived based on the Java swagger configuration. Based on this configuration, multiple YAMLs will be generated. Swagger UI will support switching between multiple configurations.

Java swagger also supports single YAML. It supports both schemes. It seems that it is just the result of different annotations. If necessary, I can also provide relevant references.

tip: The final generated YAML is in line with the swagger specification, but in terms of user and dev experience, it will be more unified and convenient.

#[OA\Configuration]
class OpenApi
{
    #[OA\GroupedOpenApi]
    public function partnerApi()
    {
        return GroupedOpenApi::builder()
            ->group("partner")
            ->pathsToMatch("/api/**")
            ->addOpenApiCustomizer(function ($openApi) {
                $openApi->getInfo()->setTitle("Partner API");
                $openApi->getInfo()->setVersion("1.1");
                $openApi->getInfo()->setDescription("This interface document is only provided to Xingrui's internal partners. Some interfaces require relevant permissions to be opened.");
            })
            ->addOperationCustomizer(function ($operation, $handlerMethod) {
                $operation->addParametersItem((new OA\Parameter())
                    ->in('header')
                    ->name('Authorization')
                    ->description("Authorization token")
                    ->required(true)
                    ->schema(type: 'string')
                );

                return $operation;
            })
            ->addOperationCustomizer($this->globalResponseMessages())
            ->build();
    }

    #[OA\GroupedOpenApi]
    public function merchantApi()
    {
        return GroupedOpenApi::builder()
            ->group("merchant")
            ->pathsToMatch("/merchantApi/**")
            ->addOpenApiCustomizer(function ($openApi) {
                $openApi->getInfo()->setTitle("Merchant API");
                $openApi->getInfo()->setVersion("1.0");
                $openApi->getInfo()->setDescription("This interface document is provided to all merchants. Some interfaces require relevant permissions to be enabled.");
            })
            ->addOperationCustomizer(function ($operation, $handlerMethod) {
                $operation->addParametersItem((new OA\Parameter())
                    ->in('header')
                    ->name('Authorization')
                    ->description("Authorization token")
                    ->required(true)
                    ->schema(type: 'string')
                );

                return $operation;
            })
            ->addOperationCustomizer($this->globalResponseMessages())
            ->build();
    }

    private function globalResponseMessages() {
        return function ($operation, $handlerMethod) {
            $method = $handlerMethod->getMethod();
            $operationAnnotation = $method->getAnnotation(Operation::class);

            $operation->getResponses()->addApiResponse(new OA\Response(response: 404, description: 'Resource not found'));

            return $operation;
        };
    }
}