I'm currently working for a company that uses Symfony 2 for its API. They also use the JMSSerializerBundle to serialize the response, but to also support different views for an entity: http://jmsyst.com/libs/serializer/master/cookbook/exclusion_strategies#creating-different-views-of-your-objects

Let me explain this better with the following example for Doctrine entities. A entity Car has a OneToMany association with the enity Part. With the API "/cars/1.json" I want to ->find() Car entity with ID one that also fetched al its childs like the Part entity. The Car entity can be put in the serializer and it will be returned. The controller for "/cars/1.json" will set the groups "Car" and "CarDetails". Because the Car entity has properties with @SER\Groups("Car") annotation and the Part entity has properties with the @SER\Groups("CarDetails") annotation, they will be returned both in the response.

But lets say we want to show a list of cars with the API call "/cars.json". Then we only want to display the car name and some other fields, but not all parts. So the controller action that handles that call with set only the group "Car" on the serializer, so only the entities and their properties that have this group will be returned.

At the moment the discoverer of swagger-php doesn't support this. It would be awesome if besides the responseClass attribute a responseGroups attribute could be added that can contain multiple values. A groups attribute could be added to a model property, to include this property of this model only if the API controller action has this Model ID as responseClass but also corresponding responseGroups.

Because models are reused in Swagger UI over mulitple APIs and we want to use the same model with different views, I'm not sure yet about how to implement this.

I hope you understand the issue and have some genius input on this :) Let me know what you think!

Hey all! I've scoured the documentation and I really can't find out the recommended way of implementing something like this:

<?php
/**
 * @OA\Parameter(
 *     parameter="station_id_required",
 *     name="station_id",
 *     description="The station ID",
 *     example=1,
 *     in="path",
 *     required=true,
 *     @OA\Schema(
 *         anyOf={@OA\Schema(type="integer", format="int64"), @OA\Schema(type="string", format="string")}
 *     )
 * )

into PHP attributes.

The closest I've been able to come so far is:

<?php
#[OA\Parameter(
        name: "station_id_required",
        in: "path",
        required: true,
        schema: new OA\Schema(),
        // new OA\Schema(type: "integer", format: "int64"),
        // new OA\Schema(type: "string", format: "string"),
]

But I'm not sure how to express the "anyOf" value for the parameter using the attributes. Nothing I'm trying is validating properly. Any ideas?

Sneak preview on attributes (requires PHP 8.1).

In fact, this is now the branch for swagger-php v4!

Feedback welcome!

So far:

• bumps major version to 4.x
• moved/renamed TokenAnalyserand Analyser
• introduced a new ReflectionAnalyser and AnnotationFactoryInterface
• introduced new AnalyserInterface implemented by both TokenAnalyser and ReflectionAnalyser
• new annotation factories added: DocBlockAnnotationFactory and AttributeAnnotationFactory; ReflectionAnalyser can use either (or possibly both at the same time...)
• updated all examples to pass with both token analyser and reflection analyser (using DocBlockAnnotationFactory)
  • this required adding classes to lots of stand-alone docblocks....
• Updated some annotation classes to also work as \Attribute
• Attribute based fixture intests/Fixtured/Apis/Attributes - this is on parity with the corresponding DocBlock example
• Allow to mix attributes and annotations
• Add PHP 8.1 to build matrix (latest deps only)

TODO:

• add all supported properties as named ctor parameters to PHP 8.1 constructors
• add more attribute based tests
• things I've missed to far :)

That issue occurs only on server side. local.ERROR: ErrorException: Multiple @OA\Response() with the same response="200": \App\Http\Controllers\Student\EventsController->update() in /var/www/html/app/Http/Controllers/Student/EventsController.php on line 136 \App\Http\Controllers\Student\EventsController->store() in /var/www/html/app/Http/Controllers/Student/EventsController.php on line 51 in /var/www/html/vendor/zircote/swagger-php/src/Logger.php:39 I tried api-docs generated on local in https://editor.swagger.io and that works very well. How that can be resolved?

Hey there,

I'm not sure if this is in the works already but after reading this post: https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

I wanted to add an issue regarding support for OpenAPI / Swagger 3.0.

Specifically, the HATEOAS implementation would be very helpful for my team.

Please let me know if any work has started on this already, otherwise I'd be happy to fork and start contributing.

Thanks in advance

After updating to the new version when I try to generate the documentation I'm getting this:

[2022-02-03 20:24:22] local.ERROR: Attribute class "JetBrains\PhpStorm\ArrayShape" not found {"exception":"[object] (Error(code: 0): Attribute class \"JetBrains\\PhpStorm\\ArrayShape\" not found at vendor/zircote/swagger-php/src/Analysers/AttributeAnnotationFactory.php:46)
[stacktrace]
#0 vendor/zircote/swagger-php/src/Analysers/AttributeAnnotationFactory.php(46): ReflectionAttribute->newInstance()
#1 vendor/zircote/swagger-php/src/Analysers/ReflectionAnalyser.php(128): OpenApi\\Analysers\\AttributeAnnotationFactory->build(Object(ReflectionMethod), Object(OpenApi\\Context))
#2 vendor/zircote/swagger-php/src/Analysers/ReflectionAnalyser.php(55): OpenApi\\Analysers\\ReflectionAnalyser->analyzeFqdn('App\\\\Classes\\\\Fin...', Object(OpenApi\\Analysis), Array)
#3 vendor/zircote/swagger-php/src/Generator.php(378): OpenApi\\Analysers\\ReflectionAnalyser->fromFile('...', Object(OpenApi\\Context))
#4 vendor/zircote/swagger-php/src/Generator.php(342): OpenApi\\Generator->scanSources(Object(Symfony\\Component\\Finder\\Finder), Object(OpenApi\\Analysis), Object(OpenApi\\Context))
#5 vendor/darkaonline/l5-swagger/src/Generator.php(181): OpenApi\\Generator->generate(Object(Symfony\\Component\\Finder\\Finder), Object(OpenApi\\Analysis))
#6 vendor/darkaonline/l5-swagger/src/Generator.php(122): L5Swagger\\Generator->scanFilesForDocumentation()
#7 vendor/darkaonline/l5-swagger/src/Http/Controllers/SwaggerController.php(60): L5Swagger\\Generator->generateDocs()
#8 vendor/laravel/framework/src/Illuminate/Routing/Controller.php(54): L5Swagger\\Http\\Controllers\\SwaggerController->docs(Object(Illuminate\\Http\\Request), 'api-docs.json')
#9 vendor/laravel/framework/src/Illuminate/Routing/ControllerDispatcher.php(45): Illuminate\\Routing\\Controller->callAction('docs', Array)
#10 vendor/laravel/framework/src/Illuminate/Routing/Route.php(262): Illuminate\\Routing\\ControllerDispatcher->dispatch(Object(Illuminate\\Routing\\Route), Object(L5Swagger\\Http\\Controllers\\SwaggerController), 'docs')
#11 vendor/laravel/framework/src/Illuminate/Routing/Route.php(205): Illuminate\\Routing\\Route->runController()
#12 vendor/laravel/framework/src/Illuminate/Routing/Router.php(721): Illuminate\\Routing\\Route->run()
#13 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(128): Illuminate\\Routing\\Router->Illuminate\\Routing\\{closure}(Object(Illuminate\\Http\\Request))
#14 vendor/darkaonline/l5-swagger/src/Http/Middleware/Config.php(44): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#15 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): L5Swagger\\Http\\Middleware\\Config->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#16 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(103): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#17 vendor/laravel/framework/src/Illuminate/Routing/Router.php(723): Illuminate\\Pipeline\\Pipeline->then(Object(Closure))
#18 vendor/laravel/framework/src/Illuminate/Routing/Router.php(698): Illuminate\\Routing\\Router->runRouteWithinStack(Object(Illuminate\\Routing\\Route), Object(Illuminate\\Http\\Request))
#19 vendor/laravel/framework/src/Illuminate/Routing/Router.php(662): Illuminate\\Routing\\Router->runRoute(Object(Illuminate\\Http\\Request), Object(Illuminate\\Routing\\Route))
#20 vendor/laravel/framework/src/Illuminate/Routing/Router.php(651): Illuminate\\Routing\\Router->dispatchToRoute(Object(Illuminate\\Http\\Request))
#21 vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(167): Illuminate\\Routing\\Router->dispatch(Object(Illuminate\\Http\\Request))
#22 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(128): Illuminate\\Foundation\\Http\\Kernel->Illuminate\\Foundation\\Http\\{closure}(Object(Illuminate\\Http\\Request))
#23 app/Http/Middleware/CorsMiddleware.php(30): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#24 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): App\\Http\\Middleware\\CorsMiddleware->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#25 vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/TransformsRequest.php(21): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#26 vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/ConvertEmptyStringsToNull.php(31): Illuminate\\Foundation\\Http\\Middleware\\TransformsRequest->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#27 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\\Foundation\\Http\\Middleware\\ConvertEmptyStringsToNull->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#28 vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/TransformsRequest.php(21): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#29 vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/TrimStrings.php(40): Illuminate\\Foundation\\Http\\Middleware\\TransformsRequest->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#30 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\\Foundation\\Http\\Middleware\\TrimStrings->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#31 vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/ValidatePostSize.php(27): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#32 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\\Foundation\\Http\\Middleware\\ValidatePostSize->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#33 vendor/laravel/framework/src/Illuminate/Foundation/Http/Middleware/PreventRequestsDuringMaintenance.php(86): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#34 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Illuminate\\Foundation\\Http\\Middleware\\PreventRequestsDuringMaintenance->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#35 vendor/fruitcake/laravel-cors/src/HandleCors.php(38): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#36 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Fruitcake\\Cors\\HandleCors->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#37 vendor/fideloper/proxy/src/TrustProxies.php(57): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#38 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(167): Fideloper\\Proxy\\TrustProxies->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#39 vendor/laravel/framework/src/Illuminate/Pipeline/Pipeline.php(103): Illuminate\\Pipeline\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#40 vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(142): Illuminate\\Pipeline\\Pipeline->then(Object(Closure))
#41 vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(111): Illuminate\\Foundation\\Http\\Kernel->sendRequestThroughRouter(Object(Illuminate\\Http\\Request))
#42 public/index.php(55): Illuminate\\Foundation\\Http\\Kernel->handle(Object(Illuminate\\Http\\Request))
#43 server.php(21): require_once('...')
#44 {main}
"} 

I've an endpoint that has optional security. So I need to generate a JSON like

     *     security={
     *          { },
     *          {"api-key": []},
     *     },

I put this annotation in my code

     *     security={
     *          { },
     *          {"api-key": {}},
     *     },

but this JSON is generated

     *     security={
     *          [ ],
     *          {"api-key": [ ] },
     *     },

instead of

     *     security={
     *          { },
     *          {"api-key": [ ] },
     *     },

This is because PHP json-serialize this structure

    ["security"]=>
    array(2) {
      [0]=> array(0) {}
      [1]=> array(1) {
        ["api-key"]=> array(0) {}
      }
    }

Any hint about where to start to fix it ?

Hi,

I currently have swagger-php generating JSON formatted documentation through the commandline util swagger.phar.

I am trying to do the same now for the models/OM but I am having issues with this. Our project currently uses Doctrine's @ ORM annotation for DB mapping and the two seem to be clashing.

My main question is (as I am not experienced with this) is @ ORM and @ SWG model annotations compatible? And if they are, do you have an example of them working in harmony?

If I include both in my annotation, the @ ORM annotation fails, causing my application to error. E.g:

https://gist.github.com/scoch/fd3efc5bb1e11a2f7fb1

I've tried swapping their order various other ways but to no avail, it usually results in a "message": "An exception was raised while creating "classnamehere"; no instance returned", error or the @ SWG model annotation above the class being ignored/ commandline error.

Thanks for any assistance you can provide.

Regards, Steven

While using the CleanUnusedComponents processor, I kept getting unused schema's in my final documentation. After looking into it a bit, it seems in most cases it includes components that are referencing each other, but that are not used anywhere else. Though some components also still showed up while not being referenced at all in the final documentation.

I've fixed it for myself by filtering the components passed to the CleanUnusedComponents processor, but I think a better fix could be thought of.

class CleanUnusedComponentsExtended
{
    public function __invoke(Analysis $analysis)
    {
	    if (Generator::isDefault($analysis->openapi->components)) {
		    return;
	    }
    
	    $this->cleanup($analysis);
    }
    
    public function cleanup(Analysis $analysis): void
    {
	    $filtered_annotations = new SplObjectStorage();
    
	    /** @var AbstractAnnotation $annotation */
	    foreach ($analysis->annotations as $annotation) {
		    $this->filterAnnotations($annotation, $filtered_annotations);
	    }
    
	    $cleanup_unused_components = new CleanUnusedComponents();
	    $analysis->annotations = $filtered_annotations;
	    $cleanup_unused_components($analysis);
    }
    
    private function filterAnnotations(AbstractAnnotation $annotation, SplObjectStorage $storage): void
    {
	    if (
		    $annotation instanceof PathItem ||
		    $annotation instanceof SecurityScheme ||
		    $annotation instanceof Info ||
		    $annotation instanceof Server ||
		    $annotation instanceof Tag ||
		    $annotation instanceof ExternalDocumentation
	    ) {
		    $storage->attach($annotation);
		    $this->traverseAnnotation($annotation, $storage);
	    }
    }
    
    private function traverseAnnotation(AbstractAnnotation $annotation, SplObjectStorage $storage): void
    {
	    foreach (array_merge($annotation::$_nested, ['allOf', 'anyOf', 'oneOff']) as $nested) {
		    if (is_array($nested)) {
			    foreach ($nested as $field_name) {
				    if (isset($annotation->{$field_name})) {
					    $this->innerTraverseAnnotation($annotation->{$field_name}, $storage);
				    }
			    }
		    } else if (isset($annotation->{$nested})) {
			    $this->innerTraverseAnnotation($annotation->{$nested}, $storage);
		    }
	    }
    }
    
    private function innerTraverseAnnotation($obj, SplObjectStorage $storage): void
    {
	    if ($obj !== null && !is_string($obj)) {
		    if (is_array($obj)) {
			    foreach ($obj as $value) {
				    $this->innerTraverseAnnotation($value, $storage);
			    }
		    } else if (!$storage->contains($obj)) {
			    $storage->attach($obj);
			    $this->traverseAnnotation($obj, $storage);
		    }
	    }
    }
}

Proposal

When using Attribute to describe specifications, we would like to synchronize the enum property with the Enum class.

I thought it would be a good idea to have the enum value automatically expanded from the Enum class name.

#[Property('status', type: 'string', enum: StatusEnum::class, example: StatusEnum::DRAFT)]
public StatusEnum status;

What we dare not do

• Allowing UnitEnum arrays to be specified. In PHP8.1, IDE and linter warn when calling EnumClass::cases() in Attribute, so it was decided not to support it at this time. For example, here are some warnings

  • Constant expression contains invalid operations
  • Cannot call abstract static method UnitEnum::cases().

Could be a problem with the PHP version, but do you have any knowledge of this issue?

Hi, I m using symfony 4.4 / nelmio api doc bundle 4.0 / swagger-php 3.0. When i try with a first example i get this error : User Notice: Required @OA\PathItem() not found

` namespace App\Controller;

use OpenApi\Annotations as OA;

/**

• @OA\PathItem(
• path="/products/{product_id}",
• @OA\Parameter(ref="#/components/parameters/product_id_in_path_required")
• ) */

class ProductController {

/**
 * @OA\Get(
 *   tags={"Products"},
 *   path="/products/{product_id}",
 *   @OA\Response(
 *       response="default",
 *       description="successful operation",
 *       @OA\JsonContent(ref="#/components/responses/product")
 *   )
 * )
 */
public function getProduct($id)
{
}

}`

I use the schema:

#[OA\Schema(schema: 'SchemaName', properties: [
    new OA\Property(property: 'property1', type: 'object', minProperties: 1, properties: [
        new OA\Property(property: 'property2', type: 'string'),
        new OA\Property(property: 'property3', type: 'string'),
    ]),
], additionalProperties: false)]

"minProperties" is ignored and says it's unknown.

The same, describing with the annotations works fine.

I have a Laravel 9 project that I updated to PHP 8.2 After the update when I run this command

php ./vendor/bin/openapi --bootstrap ./tools/swagger-constants.php --output ./public/swagger ./config/swagger.php ./app

I got a lot of error messages:

How can I fix those error messages?

The package version installed is 3.3.6

Hard way

Using doctrine @NamedArgumentConstructor

What are the benefits?

• Removing all attribute classes (or vice versa, keep the attribute classes and remove the annotation classes)
• The whole structure will be clearly visible when declaring sub annotations
• Strict format - you will see the error if you try to add unrelated sub annotation or not expected data type (now they are just ignored)
• Annotation's and Attribute's classes could be combined without any additional magic (about magic check this example)

What are the disadvantages?

• This is a breaking change.
• Change all annotations in the Examples folder. (I didn't find any automated solutions, so only manually)
• Might need to fix some tests.
• Need to change the inheritance structure a bit: almost all annotation classes will have to inherit only the AbstractAnnotation class if they have a custom set of arguments in the constructor.
  • Basically there are problems only with classes that inherit Schema, but I checked if it is possible to use trait + interface and yes, it will work with a few changes in business logic.
  • Add an AbstractAnnotation::create(array $properties) method so that you can instantiate the Annotation class with _context as it is now (will be used as an internal method).

Simple way (magic)

In each annotation class, can be added the first argument, which takes an array of any keys and values (this is how the class is instantiated from annotations) An example of how it is implemented in another library.

What are the benefits?

• Not many changes
• Removing all attribute classes (or vice versa, keep the attribute classes and remove the annotation classes)
• The whole structure will be clearly visible when declaring sub annotations
• Potentially not everyone will have BC (will not be for those who use only named arguments with OA attributes

What are the disadvantages?

• Anyone using OA attributes without named arguments will still have BC
• Need to change the inheritance structure a bit

Reply if you are interested or not, thanks.

This allows you to create custom attributes like this:

use OpenApi\Attributes\Parameter;

#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_PARAMETER | \Attribute::IS_REPEATABLE)]
class QueryParameter extends Parameter
{
    public $in = 'query';
}

And use it in a class method like this:

public function index(#[QueryParameter] ?string $name) {}

A similar solution can be done for Cookie, Header and RequestBody, I can try to implement them inside the library itself, if you want

I'm building something on a newer version of Laravel, where the recommendation is to move to separate controllers for each route, but this doesn't seem to behave as expected when generating the OpenAPI structure. The operationId for each route is different

A controller such as the following behaves as expected:

class CombinedController extends Controller
{
  #[OA\Get(
  path: '/endpoint'
  ...
  )]
  public function get ()
  {...}
  
  #[OA\Patch(
  path: '/endpoint'
  ...
  )]
  public function update()
  {...}
}

"paths": {
  "/endpoint": {
    "get": {
    }
    "patch": {
    }
  }
}

Separating these into two different classes seems to not merge the paths together correctly:

class GetController extends Controller
{
  #[OA\Get(
    path: '/endpoint'
    ...
  )]
  public function __invoke()
  {...}
}

class PatchController extends Controller
{
  #[OA\Patch(
    path: '/endpoint'
    ...
  )]
  public function __invoke()
  {...}
}

"paths": {
  "/endpoint": {
    "get": {
    }
  }
}

Am I doing something incorrectly, or is this an issue which needs looking into?