Nelmioapidocbundle: Update zircote/swagger-php to version 3

[AndriiChymyrys]

Could you please update zircote/swagger-php to 3 version because I and maybe someone else need some futures from there?

[GuilhemN]

It is not released yet, and we need to update https://github.com/GuilhemN/swagger first, help welcome this is a huge task :)

[Jean85]

zircote/swagger-php v3 has been released!

[lucacavallaro]

Any update on this?

[GuilhemN]

https://github.com/GuilhemN/swagger still needs to be updated but I can't dedicate it the time that would be necessary, contributions still welcome ;)

[calbrecht]

To get into the topic i cloned the NelmioApiDocBundle and started poking around. Eventually this led me to the conclusion it would be better not to have the swagger-php functionality duplicated in swagger and therefore having to maintain a layer in between that needs to be updated before the update of the swagger-php version.

Now after i have removed the dependency to swagger by replacing its functionality with static methods in a Util class and adjusting the calls from within NelmioApiDocBundle classes, making all tests pass again and cleaning up here and there some bits, maybe you are willing to have a look at it?

https://github.com/mayflower/NelmioApiDocBundle/tree/refactor-swagger

I like to continue testing the rest of introduced functionality that isn't tested yet and then open a pull request here to get the changes merged, to be able to discuss the next refactoring on that basis, that would be to make the NelmioApiDocBundle work with the newer version of swagger-php.

[GuilhemN]

That's a very interesting approach! I'm a bit worried about releasing a new major (3.x is not old...), but I guess it's worth it and I will most likely maintain 3.x for some time anyway.

I look forward to learning more about your proposal ☺

[goetas]

If the update path from 3.x to 4.x is simple and clear, probably a new major release should be not a problem

[goetas]

Checked now the changes... a lot of renames :(

[calbrecht]

@goetas Yes, because that is what they are, the methods are named like *Definition, *Property.
The actual parameters to this methods are in fact instances of those Annotations named like so, why not name the variables to what they are?

[goetas]

Naming is one of the most common BC breaks in most of the libraries... sadly they do not add any advantage to the library itself. But this is how life it goes :)

[calbrecht]

In this case it adds clarity and stricter type hinting and honestly i don't see where this is a library whose methods are consumed from outside, correct me if i'm wrong.

[mantis]

https://github.com/nelmio/NelmioApiDocBundle/pull/1623 would make the change to OpenApi 3

[GuilhemN]

Closing this as #1623 is no longer wip and will soon land in the bundle :)